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1. Introduction 

1.1 Purpose 

In this document we introduce the Lisp programming environment of the Symbolics Lisp 
Machine. Using a single example program, we present one style of interacting with that 
environment in developing Lisp programs. We do not prescribe a "best" style of programming 
on the Lisp Machine. Rather, we suggest some techniques and combinations of features that 
expert Lisp Machine programmers advocate. You might find these techniques useful in 
developing a comfortable and efficient Lisp Machine programming style of your own. 

1.2 Prerequisites 

This document is for you if you will be writing or maintaining Lisp programs and have recently 
begun to use a Lisp Machine. The document will be most useful if you have some experience 
writing Lisp programs and are familiar with basic features of the Lisp Machine. The document 
is not a survey of Lisp Machine facilities, a reference manual, or a Lisp primer. You might 
find the following Symbolics publications helpful when reading this document: 

• Lisp Machine Summary 

• Program Development Help Facilities 

• Lisp Machine Manual 

• An up-to-date set of release notes 

1.3 Scope 

We focus in this document on interaction between programmers and the Lisp Machine. We 
present some ways of using Lisp Machine features that you might find helpful at each stage of 
program development. We mention some broad issues of style in designing programs, including 
modularity and efficiency, but we do not explore program structure in any depth. We do not 
discuss matters of style in using Lisp, such as appropriate uses for structures and flavors. 

This document corresponds to the Symbolics 3600. Some key bindings and symbol names are 
different on the Symbolics LM-2. 

1 .4 Method 

We derived the methods we describe here by working with Lisp Machine programmers at 
Symbolics. Some of these programmers were early developers of the machine itself. Their 
styles vary. Like most programmers, they generally do not follow a simple textbook sequence 
of designing, coding, compiling, debugging, recompiling, testing, and debugging again. Instead, 
they develop programs in repeated cycles, each a sequence of editing, compiling, testing, and 
debugging. These cycles are often nested. For example, an error in testing a program invokes 
the Debugger; from the Debugger the programmer types Lisp forms or calls the editor to 
change and recompile code; an error in retesting code from the Debugger invokes the Debugger 
again. 
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1.5 Features 

Symbolics developers have designed the Lisp Machine to accommodate a relatively spontaneous 
and incremental programming style. Five Lisp Machine features make up an integrated 
programming environment. 

• The Zetalisp environment. The Lisp system code allows you to write 
programs that are extensions of the environment itself. You can often 
produce complex programs with comparatively little new code. Zetalisp 
flavors let you build data structures with complex modular combinations of 
associated procedures and state information. 

• The window system. Windows permit you to shift rapidly among such 
activities as editing, evaluating Lisp, and debugging. You can suspend an 
activity in one window, switch to another, and return to the first without 
losing its state. You can display several activities on the same screen. 
Because the window system is itself implemented with Zietalisp flavors, you 
can modify or create windows for special displays. 

• The Zmacs text editor. Zmacs has sophisticated means of keeping track of 
Lisp syntax. It interacts with the Zetalisp environment, letting you find out 
about existing code and incorporate it into your programs. Unlike some 
structure editors, Zmacs allows you to leave definitions incomplete until you 
are ready to evaluate or compile them. 

• Dynamic compiling, linking, and loading. The compiler is always loaded. 
You can use single-keystroke commands to compile and load source code 
from a Zmacs buffer. You can write, compile, test, edit, and recompile code 
in sections. When you recompile a function definition, the function's callers 
use the new definition. 

• Interactive debugging. Errors invoke the Debugger in then- dynamic 
environments. From the Debugger you can examine the stack, change 
values of variables and arguments, call the editor to change and recompile 
source code, and reinvoke functions. 

1.6 Organization 

The sequence of steps in developing a program on the Lisp Machine is too complex to mirror 
in the linear organization of a document. We emphasize the cyclical course of program 
development, but we have organized he document in a simple way. We present the main 
programming sequence in the next three chapters. These deal simply with writing and editing, 
evaluating and compiling, and debugging code. We discuss particular Zetalisp functions, Zmacs 
commands, and other features where they appear most useful or where they present alternatives 
to common techniques. 

The next three chapters require virtually no knowledge of flavors or the window system. But 
knowing about flavors and windows is essential to advanced use of the Symbolics Lisp Machine. 
Chapter 5 presents some simple uses of flavors and windows and some programming aids for 
working with them. 
Throughout, we use as an example the development of a single program that draws the 
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recursive arrows in the cover design for this document. Sandy Schafer and Bernard LaCasse of 

Schafer/LaCasse created the original design. Richard Bryan of Symbolics wrote and we revised 

a Lisp program that simulates it. The complete code appears in appendixes A (page 133) 

and B (page 147) and in the files SYS: EXAMPLES; ARROW-CALC LISP and 

SYS: EXAMPLES; ARROW-OUT LISP. (To run the program, load 

SYS: EXAMPLES; ARROW.) A reproduction of the design produced on a Symbolics LGP-1 

Laser Graphics Printer appears in appendix C (page 165). 

Many of the techniques and facilities we mention are helpful at more than one stage of 
program development. Conversely, the Lisp Machine provides many paths for accomplishing 
tasks at each stage. As programmers at Symbolics gladly acknowledge, there is more than one 
way to do almost anything on the Lisp Machine. 

1.7 Notation Conventions 

Modifier keys are designed to be held down while pressing other keys. They do not themselves 
transmit characters. A combined keystroke like METfl-X is pronounced "meta x" and written as 
m-X. This notation means press the METfl key and, while holding it down, press the X key. 

Modifier keys are abbreviated as follows: 
Key Abbreviation 
CTRL c- 
METfl IB- 
SUPER s- 
HYPER h- 
SHIFT sh- 

The keys with white lettering (like X or SELECT) all transmit characters. Combinations of 
these keys are meant to be pressed in sequence. This sequence is written as, for example, 
SELECT L. This notation means press the SELECT key, release it, and then press the L key. 

This document uses the following notation conventions: 

Appearance in document Representing 

send, chaos:host-ap Printed representation of Lisp objects in running text. 

RETURN, ABORT, c-F Keyboard keys. 

SPACE Space bar. 

login Literal type-in. 

(make -symbol "foo") Lisp code examples. 

(function-name argl areZ) Syntax description of the invocation of fanction-name. 

Of'gl Argument to the function function-name, usually expressed as a 

word that reflects the type of argument (e.g., string), 
grgi Optional argument; you can leave it out. 

Undo, Tree Edit Any Command names in Zmacs and Zmail appear with initial letter of 

each word capitalized. 
Insert File (m-X) Extended command names in Zmacs and Zmail. Use m-X to 

invoke one. 
(Map Over] Menu items. 

(L), (R2) Mouse clicks: L=left, L2=double click left, M=middle, 

M2=double click middle, R=right, R2=double click ri^t. 
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Mouse commands use notations for menu items and mouse clicks in the following ways: 

1. Square brackets delimit a mouse command. 

2. Slashes (/) separate the members of a compound mouse command. 

3. The standard clicking pattern is as follows: 

• For a single menu item, always click left. For example, the following two 
commands are exactly the same: 

[Previous] 
[Previous (L)] 

• For a compound command, always click right on each menu item except the 
last, where you click left. For example, the following two compound 
commands are exactly the same: 

[Map Over / Move / Hardcopy] 

[Map Over (R) / Move (R) / Hardcopy (L)] 

4. When the notation does not follow the standard, it shows explicitly which 
button to click. For example: 

[Map Over / Move (M)] 
[Previous (R)] 

In the sections of this document that develop the Lisp code for the example program, we use 
change bars to distinguish new or changed code from code that we have already presented. 
Whenever we display a line of code that has not appeared before, and whenever we change a 
line of code that has already appeared, we place a vertical bar (|) next to that line in the left 
margin. This bar is not part of the code itself. In the following example, we change two lines 
of the definition of draw-big-arrow: 

(defun draw-blg-arrow () 

;; Determine coordinates of arrowhead vertexes 
(multiple-value-bind 
(•plx» 'ply* 'pZx* "pZy 'pSx* "pSy* "pex* *p6y*) 

(compute-arrowhead-polnts) 
:: Determine coordinates of shaft vertexes 
(mu1t1p1e-va1ue-b1nd ("pSx* 'pSy* 'pAx* 'pAy') 
(compute-arrow-shaft-points) 
(draw-blg-outHne) ;0ut11ne arrow 

(when 'do-the-strlpes* 

(stripe-arrowhead))))) ;Str1pe head 
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2. Writing and Editing Code 



Symbolics Lisp Machine programmers seldom write programs in sequence, from beginning to 
end, before testing them. They often leave definitions incomplete, skip to other definitions, and 
then return to finish the incomplete forms. They search for existing code to incorporate into 
new programs. They edit their work frequently, changing code while writing, testing, and 
maintaining programs. 

In this chapter we discuss Lisp Machine features, particularly Zmacs commands and Zetalisp 
functions, that make this style natural. Many of these features are useful at other stages of 
programming as well: Editing techniques are important in program maintenance, and methods 
of learning about existing code are helpful in debugging. 

To illustrate programming methods, we develop a program that draws the recursive arrow 
design that appears on the cover of this document. (The program does not draw the horizontal 
stripes outside the large arrow.) We produce the figure on a Symbolics LGP-1 Laser Graphics 
Printer, a Lisp Machine screen, or a file. We develop the program in four stages, beginning 
with simple procedures to outline the arrows and progressively modifying the code to refine the 
figure: 

\. Drawing the borders of the large arrow and of the smaller recursively 
drawn arrows that it encloses 

2. Drawing the diagonal stripes within the figure, but with uniform thickness 
and spacing 

3. Changing the stripes to vary in thickness and spacing 

4. Writing the routines that control the output destination 

Appendixes A (page 133), B (page 147), and C (page 165) contain the code for the sample 
program and a reproduction of the LGP image the program produces. 

2.1 Before You Begin 

Use the Zmacs text editor to write and edit programs. Zmacs has many features that provide 
information about Zmacs commands, existing code, buffers, and files. Two features are 
generally useful: the HELP key and completion. (See Program Development Help Facilities for 
details.) 

2.1.1 HELP 

Pressing the HELP key in a Zmacs editing window gives information about 
Zmacs commands and variables. The kind of information it displays 
depends on the key you press after HELP. 

Reference 

HELP ? Displays a summary of HELP options. 

HELP fl Displays names, key bindings, and brief descriptions of 

commands whose names contain a string you specify. 
(fl refers to "apropos".) 
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HELP C 



HELP 


D 


HELP 


L 


HELP 


U 


HELP 


U 


HELP 


U 


HELP 


SPfiCE 



Displays the name and brief description of a command 
bound to a key you specify. 

Displays long documentation for a command you specify. 

Displays a listing of the last 60 keys you pressed. 

Offers to "undo" the last major Zmacs operation, such as 
sorting or filling, when possible. 

Displays the names and values of Zmacs variables whose 
names contain a string you specify. 

Displays the key binding for a command you specify. 
(M refers to "where".) 

Repeats the last HELP command. 



2.1.2 Completion 

Some Zmacs operations require you to provide names — for example, names 
of extended commands. Lisp objects, buffers, or files. You usually supply 
names by typing characters into a minibuffer that appears near the bottom 
of the screen. Often you do not have to type all the characters of a name; 
Zmacs offers completion over some name spaces. When completion is 
available, the word "Completion" appears in parentheses above the right side 
of the minibuffer. 

You can request completion when you have typed enough characters to 
specify a unique word or name. For extended commands and most other 
names, completion works on initial substrings of each word. For example, 
ffl-x c b is sufficient to specify the extended command Compile Buffer. 
SPACE, COMPLETE, RETURN, and END complete names in different ways. 
HELP and [Zmacs V/indow (R)] list possible completions for the characters 
you have typed. 



Reference 

SPACE 

HELP or C-? 

[Zmacs Window (R)] 

COMPLETE 
RETURN or END 



Completes words up to the current 
word. 

Displays possible completions in the 
typeout area. 

Pops up a menu of possible 
completions. 

Displays the full name if possible. 

Confirms the name if possible, 
whether or not you have seen the full 
name. 
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2.2 Getting Started 

When Symbolics programmers begin to write new Lisp programs, they often follow these steps: 

1. Enter the Zmacs editor. 

2. Create a buffer for a new file for the program. 

3. Set the attributes of the buffer and file, including major and minor modes. 



2.2.1 Entering Zmacs 

Use SELECT E or [Edit] from a system menu to enter Zmacs. 

Reference 

SELECT E Selects a Zmacs frame. 

[Edit] (from a system menu) Selects a Zmacs frame. 



2.2.2 Creating a File 

To store program code in a new file, use Find File (c-X c-F) to create a 
buffer for the file at the beginning of the editing session. You can then 
edit the file's attributes or create an attribute list that appears in the text 
(see section 2.2.3, page 7). You will not have to interrupt later work to 
name the file or check its attributes before you save it. 

Reference 

Find File (c-X c-F) Creates and names a buffer for the 

file, reading in the file if it already 
exists. 



2.2.3 File Attribute Lists 

Each buffer and generic pathname has attributes, such as Package and Base, 
which can also be displayed in the text of the buffer or file as an attribute 
list. An attribute list must be the first nonblank line of a file, and it must 
set off the listing of attributes on each side with the characters "-*-". If 
this line appears in a file, the attributes it specifies are bound to the values 
in the attribute list when you read or load the file. 

Suppose you want the new program to be part of a package named 
graphics that contains graphics programs. In this case, you want to set the 
Package attribute to graphics in three places: the generic pathname's 
property list; the buffer data structure; and the buffer text. You can make 
the change in two ways: 

• If the package already exists in your Lisp environment, use Set Package 
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(m-X) to set the package for the buffer. The command asks you whether or 
not to set the package for the file and attribute list as well. You cannot 
use this command to create a new package. 

• Use Update Attribute List (m-X) to transfer the current buffer attributes to 
the file and create a text attribute list. Edit the attribute list, changing the 
package. Use Reparse Attribute List (m-X) to transfer the attributes in the 
attribute list to the file and the buffer data structure. If the package you 
specify by editing the attribute list does not exist in your Lisp environment, 
Reparse Attribute List asks you whether or not to create it under global. 

When you specify a package by editing the attribute list, you can explicitly 
name the package's superpackage and, if you want, give an initial estimate 
of the number of symbols in the package. (If the number of symbols 
exceeds this estimate, the name space expands automatically.) Instead of 
typing the name of the package, type a representation of a list of the form 
{package superpackage symbol-count) . To indicate that the graphics 
package is inferior to global and might contain 1,000 symbols, type into the 
attribute list: 

Package: (GRAPHICS GLOBAL ICOO) 

See the Lisp Machine Manual, section 21.9.2, page 369, and Release 4.0 
Release Notes, sections 5.3.5 and 5.3.6, page 90, for more on file and buffer 
attributes. 

Example 

Suppose the package for the current buffer is user and the base is 8. We 
want to create a package called graphics for the buffer and associated file. 
We also want to set the base to 10. If no attribute list exists, we use 
Update Attribute List (m-X) to create one using the attributes of the 
current buffer. An attribute list appears as the first line of the buffer: 

;;; -•- Mode: LISP; Package: USER; Base: 8 -«- 

Now we edit the buffer attribute list to change the package specification 
from USER to (GRAPHICS GLOBAL 1000) and to change the base specification 
from 8 to 10. The text attribute list now appears as follows: 

;;; -»- Mode: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 -•- 

Finally, we use Reparse Attribute List (m-X). The package becomes 
graphics and the base 10 for the buffer and the file. 
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Reference 

Set attribute (m-X) 



Update Attribute List (m-X) 



Reparse Attribute List (m-X) 



Sets attribute for the current buffer. 
Queries whether or not to set 
attribute for the file and in the text 
attribute list, attribute is one of the 
following: Backspace, Base, Fonts, 
Lowercase, Nofill, Package, Patch 
File, Tab Width, or Vsp. 

Assigns attributes of the current 
buffer to the associated file and the 
text attribute list. 

Transfers attributes from the text 
attribute list to the buffer data 
structure and the associated file. 



2.2.4 Major and Minor Modes 

Each Zmacs buffer has a major mode that determines how Zmacs parses the 
buffer and how some commands operate. Lisp Mode is best suited to 
writing and editing Lisp code. In this major mode, Zmacs parses buffers so 
that commands to find, compile, and evaluate Lisp code can operate on 
definitions and other Lisp expressions. Other Zmacs commands, including 
LINE, TAB, and comment handlers, treat text according to Lisp syntax rules 
(see section 2.4, page 19). 

If you name a file with one of the types associated with the canonical type 
:lisp, its buffer automatically enters Lisp Mode. Following are some 
examples of names of files of canonical type :Iisp: 



Host system 
Lisp Machine 
TOPS-20 
UNIX 



File name 

acme-b1ue:>syn!bo1ics>examples>arrow.lisp 
acme-20:<syinbo11cs.exanip1es>arrow.1isp 
acms-vax : /symbol 1 cs/exanples/arrow. 1 



You can also specify minor modes, including Electric Shift Lock Mode and 
Atom Word Mode, that affect alphabetic case and cursor movement. 
Whether or not you use these modes is a matter of personal preference. If 
you want Lisp Mode to include these minor modes by default, you can set a 
special variable in an init file. If you want to exit one of these modes, 
simply repeat the extended command. The command acts as a toggle switch 
for the mode. 
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Example 

The following code in an init file makes Lisp Mode include Electric Shift 

Lock Mode if the buffer's Lowercase attribute is nil, as it is by default: 

(login-forms 
(setq zwe1:1lsp-mode-hook 

'zwe1 :e1ectric-shift-lock-1f -appropriate)) 



Reference 
Lisp Mode (m-X) 



Electric Shift Lock Mode (m-X) 



Atom Word Mode (m-X) 



Auto Fill Mode (m-X) 



Set Fill Column (c-X F) 



Treats text as Lisp code in parsing 
buffers and executing some Zmacs 
commands. 

Places all text except comments and 
strings in upper case. 

Makes Zmacs word-manipulation 
commands (such as ro-F) operate on 
Lisp symbol names. 

Automatically breaks lines that 
extend beyond a preset fill column. 

Sets the fill column to be the column 
that represents the current cursor 
position. With a numeric argument 
less than 200, sets the fill column to 
that many characters. With a larger 
numeric argument, sets the fill 
column to that many pixels. 



2.3 Program Development: Design and Figure Outline 



2.3.1 Program Strategy 

Our goal in developing the sample program is to reproduce the pattern of 
striped arrows on the cover of this document. The pattern consists of one 
large arrow enclosing many small arrows that are similar to each other. 
Each arrow is a series of line segments that form either its outline or its 
stripes. 

We have two general problems in writing the program. We must calculate 
the position of each line segment we want to draw. We must also convert 
these positions into a form that will produce line segments on the output 
device we choose. 

In solving these problems, we want to adhere to two principles: 
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• We want the program to be as modular as possible. The routines that 
calculate line positions should not depend on the output device we choose. 
The routines that translate positions for the output device should not 
depend on any particular method of calculating those positions. If we want 
to change the internal operation of either set of routines, we should not 
have to change the other. 

• We want to write the program in an incremental style. We write the 
program in stages, producing a working version at each stage. We start 
with simple tasks and gradually add refinements until we are satisfied with 
what the program accomplishes. 

We write the program in two modules, one to calculate line positions and 
the other to translate positions for the output streams. We put these 
modules in separate files: The first appears in appendix A (page 133), the 
second in appendix B (page 147). 

How do we send line positions from the module that calculates them to the 
module that transmits them to output? The output module, which we 
discuss in detail in chapter 5 (page 101), consists of definitions of flavors 
and methods to transfer information to the appropriate output stream. 
Streams for LGP and screen output can both produce lines using the 
coordinates of the endpoints. Our module that calculates line positions 
needs to compute the coordinates of the endpoints of the lines to be drawn. 
In the output module, we define a generic operation called :show-!ines to 
receive the coordinates from the calculation module and translate them for 
the appropriate output stream. The calculation module sends :show-Iines 
messages to the output module. We can decide at run time which output 
stream to use. 

Now that we have defined the interface between the two modules, we could 
in principle write either module first. Although we want the position- 
calculating routines to be independent of the output device, we have to 
choose a coordinate system for the calculations. For ease of interpretation, 
we place the origin at bottom left. This is the convention that the system 
LGP routines use, but the origin for screen coordinates is at top left. For 
the sake of convenience, we calculate positions in units of LGP pixels. 

2.3.2 Simple Screen Output 

We discuss the output routines in chapter 5 (page 101). Eventually, we 
want to produce output on the screen, an LGP, or a file. To develop the 
program, we need a routine for simple screen display so that we can check 
the results of our calculation routines. We can use the stream that is the 
value of terminal-io. This stream handles idraw-line messages whose 
arguments include the coordinates of the endpoints of the lines to be drawn. 
(See Introduction to Using the Window System, section 2.4, page 30, for more 
on :draw-line.) 
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We first create a source file for the output routine. We define a flavor, 
screen-arrow-output, and a method to handle :show-lines messages from 
the calculation routines. The arguments to :show-Iines are the coordinates 
of the endpoints of one or more lines to be drawn. If the message has more 
than four arguments — the coordinates of two endpoints — we assume that 
we are to draw more than one line, each starting at the endpoint of the last. 
The :show-lines method must iterate over the arguments of the message 
and send terminal-io a :draw-line message for each line to be drawn. 

We must remember to transform the y-coordinate to take account of the 
screen's origin at the top. We must also scale both coordinates to take 
account of the LGP's higher resolution: Screen pixels are about 2.5 times as 
large as LGP pixels. 

The following code provides this simple output module: 

(def flavor screen-arrow-output 
((scale-factor 2.5)) 
()) 

(defmethod (screen-arrow-output :show-11nes) 
(x y &rest x-y-pairs) 
(loop for xO = (send self ':compute-x x) then xl 
for yO = (send self ':compute-y y) then yl 
for (xl yl) on x-y-paIrs by #'cddr 
do (setq xl (send self ':conipute-x xl) 
yl (send self ':coinpute-y yl)) 
(send termlnal-lo ':draw-line 

xO yO xl yl tv:alu-ior t))) 

(defmethod (screen-arrow-output :compute-x) (x) 
(fixr (// X scale-factor))) 

(defmethod (screen-arrow-output :compute-y) (y) 
(fixr (- 800 (// y scale-factor)))) 



2.3.3 Outlining the Figure 

We now begin to write the module that calculates the coordinates of the 
lines that make up the figure. First we must decide how to represent the 
large arrow that encloses the figure and the smaller arrows inside it. As the 
diagram in appendix A (page 133) shows, seven points define each arrow. 
Each arrow has a head, bounded by points 0, 1, and 6, and a shaft, bounded 
by points 2, 3, 4, and 5. The large outer arrow and the smaller inner 
arrows differ in their shafts. Each inner arrow has two yet smaller arrows 
beneath it. The inferior arrows overlap the shafts of the superior arrows 
and turn each shaft into a series of descending triangles. 

We have two kinds of arrow, represented by the large outer arrow and the 
small inner ones. We can treat these differences in several ways: 
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• We can define two structures, make each arrow an instance of one of the 
structures, and store information about each arrow in the structure's slots 
(see the Lisp Machine Manual, chapter 19, page 257). 

• We can define two flavors, make each arrow an instance of one of the 
flavors, and store information about each arrow in the flavor's instance 
variables (see the Lisp Machine Manual, chapter 20, page 279). 

We can simply define global variables to represent the state of the current 



arrow. 



Whichever method we choose, some operations, such as striping the 
arrowheads, will be the same for both kinds of arrows. Other operations, 
such as striping the shafts, will depend on the kind of arrow we are 
drawing. 

For simplicity, we use global variables to hold information about the arrows, 
and we use functions to define procedures for calculating coordinates. Note 
that we bind the global variables rather than set them. We do this because 
we might eventually have two or more arrow programs running at the same 
time in separate processes. If we set global variables, one program might 
incorrectly use a value set by another (see section 5.1.6, page 117). 

Our first task in writing the calculation module is to outline the arrows. 
After creating a file for the module, we write the code for this task in six 
steps: 

1. Define variables to hold information about the arrow we are drawing. For 
the :show-lines message we need the x- and y-coordinates of the seven 
points that define the arrow. We also need the length of the top edge of 
the arrow, which we use as a base length. In calculating coordinates, we 
also need the values of one-half and one-fourth the length of the top edge. 
We use def var to declare global variables near the beginning of the file (see 
the Lisp Machine Manual, section 3.1, page 14). This macro declares 
variables special for the compiler and lets us supply default initial values and 
documentation strings. By convention, we surround the names of global 
variables with asterisks to distinguish them from names of local variables. 



(defvar 'top-edge* nil 

"Length of the top edge of the arrow") 

(defvar 'top-edge-Z* nil 
"Half the length of the top edge") 

(defvar »top-edge-4« nil 

"One-fourth the length of the top edge") 

(defvar "pOx* nil 

"X-coordinate of point 0") 
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(defvar 'pOy* nil 
"Y-coord1nate of point 0") 

(defvar *plx« nil 
"X-CGord1nata of point 1") 

(defvar »ply» nil 

"Y-coordinate of point 1") 

(defvar »p2x» nil 

"X-coordinate of point 2") 

(defvar 'pZy* nil 

"Y-coordinate of point 2") 

(defvar 'pSx* nil 

"X-coordinate of point 3") 

(defvar »p3y» nil 

"Y-coordinate of point 3") 

(defvar «p4x« nil 

"X-coordinate of point 4") 

(defvar *p4y« nil 

"Y-coordinate of point 4") 

(defvar 'pBx* nil 

"X-coordinate of point 5") 

(defvar 'pSy* nil 

"Y-coordinate of point 5") 

(defvar 'pSx* nil 
"X-coordinate of point 6") 

(defvar 'pey* nil 
"Y-coordinate of point 6") 

2. Define an initial function, draw-arrow-graphic, for the calculation module. 
We will call this function from the one we invoke to start the program. We 
pass draw-arrow-graphic the length of the top edge of the large arrow and 
the coordinates of its top right point (point 0). These arguments determine 
the position and size of the arrow. The function also calculates the half 
and quarter lengths of the top edge. 



(defun draw-arrow-graphic (»top-edge* *pOx» 'pOy*) 
(let ((*top-edge-2» (// 'top-edge* 2)) 

(*top-edge-4* (// "top-edge* 4))))) 
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3. Outline the large arrow. We compute the coordinates of the other six 
points of the arrow, then send a :show-llne$ message to draw the lines. We 
can calculate the coordinates of points 1, 2, 5, and 6 the same way for both 
the large and small arrows. We put these calculations in a separate function 
so that we can use the same code for both kinds of arrow. We need a 
constant to hold the destination of the :show-llnes messages. We must add 
to draw-arrow-graphic a call to draw-big-arrow. 

(defconst *dest* nil 

'Destination of :SHOW-LINES messages to output") 



(defun draw-arrow-graph 1c («top-edge* »pOx» »pOy») 
(let ((»top-edge-2* (// »top-edge« 2)) 
(•top-edge-4» (// »top-edge» 4))) 
(draw-big-arrow))) 



(defun draw-big-arrow () 
(multlple-value-blnd 

(•plx* "ply* »p2x» •p2y* 'pSx* «p5y« »p6x* 'pey*) 

(compute-arrowhead-points) 
(multlple-value-blnd (*p3x* 'pSy* »p4x« •p4y«) 
( compute-arrow- shaft-po 1 nts ) 
(draw-b1g-outl1ne)))) 

(defun compute-arrowhead-points () 
(let» ((plx (- "pOx* »top-edge»)) 
(ply "pOy*) 

(p2x (+ plx •top-edge-4«)) 
(p2y (- *pOy» nop-edge-4»)) 
(p6x «pOx*) 

(p6y (- »pOy* »top-edge«)) 
(p5x (- 'pOx* •top-edge-4«)) 
(p5y (+ p5y »top-edge-4»))) 
(values plx ply p2x p2y p5x p5y p6x p6y))) 

(defun compute-arrow-shaft-polnts () 
(values (- *plx« •top-edge-4*) 
(- »p2y« »top-edge-2») 
•p2x» 
(- •p2y» 'top-edge*))) 



(defun draw-b1g-out11ne () 
(send 'dest* ':show-11nes 

»pOx« 'pOy* »plx» »ply« •p2x» *p2y» 'pSx* «p3y« 
*p4x» •p4y» 'pSx* «p5y» «p6x» 'pey* 'pOx* 'pOy*)) 



4. Outlme the largest of the small arrowheads. We can generate all the 
interior outlines in the figure by outlining only the heads of the small 
arrows. We first draw the largest of these arrowheads by analogy with our 
drawing the large arrow. We can use our function 
compute-arrowhead-poiHts to calculate the coordinates of the vertexes. 
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First we need to halve the value of *top-edge* and bind new values for the 
coordinates of the top right point of the arrow. 



(defun draw- arrow- graphic («top-edge« "pOx* 'pOy') 
(let ((«top-edge-2» (// »top-edge« 2)) 
(»top-edge-4» (// »top-edge» 4))) 
(draw-big-arrow) 
(let (("top-edge* •top-edge-2») 

(*pOx* (- *pOx« »top-edge-2*)) 
(»pOy» (- 'pOy* *top-edge-2»))) 
(do-arrows)))) 

(defun do-arrows () 

(let ((»top-edge-2» (// 'top-edge* 2)) 
(•top-edge-4* (// *top-edge* 4))) 
(draw-arrow))) 

(defun draw-arrow () 
(multiple-value-bind 

(*plx* *ply* *p2x» *p2y* 'pSx* *p5y* *p6x« *p6y») 

(compute-arrowhead-points) 
(draw-outline))) 

(defun draw-outline () 

(send »dest* ':show-lines *p2x* *p2y* *plx* *ply* 
•pOx* *pOy* 'pex* *p6y* "pSx* *p5y*)) 

i. Outline the rest of the small arrows. Each small arrow has two inferior 
arrows beneath it. We modify our function do-arrows by adding two 
recursive function calls: one to draw the left-hand inferior of each superior 
arrow, and one to draw the right-hand inferior. We limit the levels of 
recursion by defining a constant, ♦max-depth*, and incrementing the 
variable *depth« on each call to do-arrows until •depth* equals 
*niax-depth*. 



(defvar *depth* 

"Level of recursion for the current arrow") 



(defconst *max-depth* 7 

"Number of levels of recursion") 

(defun draw-arrow-graphic (*top-edge* *pOx* *pOy*) 
(let (('top-edge-Z* (// »top-edge» 2)) 
(*top-edge-4* (// *top-edge* 4))) 
(draw-big-arrow) 
(let ((«top-edge* *top-edge-2*) 

(*pOx* (- *pOx* •top-edge-2*)) 
(*pOy* (- *pOy* *top-edge-2*)) 
(*depth« 0)) 
(do-arrows)))) 
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(defun do-arrows () 

(when (< »depth» •tnax-depth») 

(let ((»top-edge-2* (// *top-edga« 2)) 
(•top-edge-4« (// nop-edge* 4))) 
(draw-arrow) 
(let (('depth* (1+ *depth»)) 

(»top-edge« •top-edge-2*) 

(•pOx* (*■ «top-edge-4« (- 'pOx* *top-edge*))) 
(*pOy« (- »pOy« •top-edga-4»))) 
(do-arrows)) 
(let (('depth* (1+ 'depth*)) 

(•top-edge* *top-edgo-2*) 
(«pOx* (- "pOx* *top-edge-4«)) 
(•pOy* (+ *top-edge-4* (- *pOy» «top-edge*)))) 
(do-arrows))))) 



6. Define a function we can call to produce the graphic. This function has to 
make an instance of screen-arrow-output, clear the screen, and call 
draw-arrow-graphic. The arguments to draw-arrow-graphic determine 
the size and placement of the figure. For now, we use estimates based on 
the dimensions, in pixels, of an LGP page. 



(defun do-arrow () 

(let ((*dest» (make-instance 'screen-arrow-output))) 
(send term1nal-1o ' :clear-screen) 
(draw-arrow-graphic 1280 1800 ISOO))) 



We now have a simple working version of our program. We first compile 
our code (see section 3.1, page 62). We then use SELECT L to select a Lisp 
Listener. There we can evaluate (graphics: do-arrow) to run the program. 
We can avoid typing the package prefix by first using pkg-goto to make the 
current package graphics: 

(pkg-goto 'graphics) 



When we run the program, we generate a screen image of the arrow 
outlines. Figure 1 (page 18) shows the output of the program at this stage. 

These six steps illustrate a pattern of incremental program development: 

• We make each function initially simple. We add new functions and edit old 
ones as tasks become more complex or refined. Facilities for keeping track 
of Lisp syntax (section 2.4, page 19) and for editing code (section 2.8, 
page 49) encourage this incremental style. 

• We compile, test, and debug code in sections as we write it. Many 
Symbolics programmers, for example, would test draw-arrow both before 
and after adding the recursive function calls. 
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08/16/83 18:31 :4& ron 



Figure 1. Program output with only the outlines of the arrows in the 
figure. 
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To support this incremental style, we must be able to check the syntax of 
our code, edit it, and compile it in sections. We discuss facilities for 
keeping track of Lisp syntax in the next section; techniques for editing code 
in section 2.8 (page 49); and methods of compiling and evaluating in 
chapter 3 (page 61). 

2.4 Keeping Track of Lisp Syntax 

Zmacs allows you to move easily through Lisp code and format it in a readable style. 
Commands for aligning code and features for checking for unbalanced parentheses can help you 
detect simple syntax errors before compiling. 

Zmacs facilities for moving through Lisp code are typically single-keystroke commands with 
c-m- modifiers. For example. Forward Sexp (c-m-F) moves forward to the end of a Lisp 
expression; End Of Definition (c-ra-E) moves forward to the end of a top-level definition. 
Most of these commands take arguments specifying the number of Lisp expressions to be 
manipulated. In Atom Word Mode word-manipulating commands operate on Lisp symbol 
names; when executed before a name with hyphens, for example. Forward Word (m-F) places 
the cursor at the end of the name rather than before the first hyphen (see section 2.2.4, 
page 9). 

See the Lisp Machine Summary for a list of common Zmacs commands for operating on Lisp 
expressions. 

2.4.1 Comments 

You can document code in two ways: You can supply documentation 
strings for functions, variables, and constants (see section 2.6, page 28); and 
you can insert comments in the source code. You can retrieve 
documentation strings with Zmacs commands and Lisp functions 
(section 2.6, page 28). The Lisp reader ignores source-code comments. 
Although you cannot retrieve them in the same ways as documentation 
strings, they are essential to maintaining programs and useful in testing and 
debugging (see chapter 3, page 61, and chapter 4, page 71). 

Most source-code comments begin with one or more semicolons. Symbolics 
programmers follow conventions for aligning comments and determining the 
number of semicolons that begin them: 

• Top-level comments, starting at the left margin, begin with three semicolons. 

• Long comments about code within Lisp expressions begin with two 
semicolons and have the same indentation as the code to which they refer. 

• Comments at the ends of lines of code start in a preset column and begin 
with one semicolon. 

You can also use #| to begin a comment and |# to end one. The comment 
can extend for more than one line. You can nest #| and |# within longer 
comments. 
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Example 

Let's add some comments to draw-arrow-graphic. We can write a top- 
level comment without regard for line breaks and then use Fill Long 
Comment (m-X) to fill it. We use c-; to insert a comment on the current 
line. We use m-LINE to continue a long comment on the next line. 



This function controls tha calculation of the coordinates of the 
endpolnts of the lines that make up the figure. The three arguments 
are the length of the top edge and the coordinates of the top right 
point of the large arrow. DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW 
to draw tha large arrow and then calls DO-ARROWS to draw the smaller 
ones. 

(defun draw-arrow-graphic ('top-edge* *pOx« 'pOy*) 
(let ((»top-edge-2« (// "top-edge* 2)) 
(*top-edge-4» (// «top-edge» 4))) 
(draw-big-arrow) ;Draw large arrow 

Length of the top-edge for the first small arrow Is half the 
length for the large arrow. Bind new coordinates for the top 
right point of the small arrow, 
(let ((»top-edge» •top-edge-2*) 

(•pOx» (- 'pOx* »top-edge-2»)) 
(•pOy* (- 'pOy* •top-edge-2«)) 
(•depth* 0)) 
(do-arrows)))) ;Draw small arrows 



Reference 

Indent For Ck)mment (c-; or m-; ) 



Kill Comment (c-m-; ) 
Down Comment Line (m-N) 

Up Comment Line (m-P) 



Inserts or aligns a comment on the 
current line, beginning in the preset 
comment column. 

Removes a comment from the current 
line. 

Moves to the comment column on the 
next line. Starts a comment if none 
is there. 

Moves to the comment column on the 
previous line. Starts a comment if 
none is there. 



Indent New Comment Line (ra-LINE) When executed within a comment, 

inserts a newline and starts a 
comment on the next line with the 
same indentation as the previous line. 



Fill Long Comment (m-X) 



When executed within a comment 
that begins at the left margin, fills the 
comment. 
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Set Comment Column (c-X ; ) 



Sets the column in which comments 
begin to be the column that 
represents the current cursor position. 
With an argument, sets the comment 
column to the position of the previous 
comment and then creates or aligns a 
comment on the current line. 



2.4.2 Aligning Code 

Code that you write sequentially will remain properly aligned if you 
consistently press LINE (instead of RETURN) to add new lines. When you 
edit code, you might need to realign it. c-m-Q and c-m-s are useful for 
aligning definitions and other Lisp expressions. 



Reference 

Indent New Line (LINE) 



Indent For Lisp (TAB or c-m-TFIB) 

Indent Sexp (c-m-Q) 
Indent Region (c-m-^) 



Adds a newline and indents as 
appropriate for the current level of 
Lisp structure. 

Aligns the current line. If the line is 
blank, indents as appropriate for the 
current level of Lisp structure. 

Aligns the Lisp expression following 
the cursor. 

Aligns the current region. 



2.4.3 Balancing Parentheses 

When the cursor is to the right of a close parenthesis, Zmacs flashes the 
corresponding open parenthesis. The flashing open parentheses, along with 
proper indentation, can indicate whether or not parentheses are balanced. 
Improperly aligned code (after you use a c-m-Q command, for instance) is 
often a sign of unbalanced parentheses. 

To check for unbalanced parentheses in an entire buffer, use Find 
Unbalanced Parentheses (m-X). Zmacs can check source files for 
unbalanced parentheses when you save the files. If a file contains 
unbalanced parentheses, Zmacs can notify you and ask whether or not to 
save the file anyway. To put this feature into effect, place tiie following 
code in an init file: 



(login-forms 

(setq zwe1:*check-unbalanced-parentheses-when-sav1ng« t)) 
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ReferencQ 

Find Unbalanced Parentheses (m-X) Searches the buffer for unbalanced 

parentheses. Ignores parentheses in 
comments and strings. 

2.5 Program Development: Drawing Stripes 

So far the sample program outlines all the arrows in the figure. The next task is to draw the 
diagonal stripes. To keep this stage as simple as possible, we ignore the differences in spacing 
and thickness of lines in the figure. We draw each stripe from upper left to lower right. We 
draw the stripes in five steps: 

1. Determine the distance between stripes. We first define a constant, 
•do-the-stripes*, that we bind to t when we want to draw stripes and nil 
when we want only outlines. We define another constant, 
•stripe-distaace*, to contain the horizontal distance between stripes. Let's 
assume we want 54 stripes in the large arrowhead. We divide the initial 
•top-edge* by 64 to obtain *stripe-distance*. 

I(defconst •do-the-strlpss* t 
"When t, permits striping of the figure") 

(defconst •stripe-distance* nil 

"Horizontal distance betv/een stripes in the large arrow") 

(defun draw-arrow-graphic (•top-edge* *pOx* *pOy*) 
(let ((•top-edge-2^ (// •top-edge* 2)) 
(•top-edge-4« (// *top-edge« 4)) 

;; Compute horizontal distance between stripes in the 
;; large arrow, assuming 64 stripes in the large 
;; arrowhead. 

(•stripe-distance* (// »top-edge« 64))) 
(draw-big-arrow) ;Draw large arrow 

;; Length of the top-edge for the first small arrow is half the 
;; length for the large arrow. Bind new coordinates for the top 
;; right point of the small arrow, 
(let (('top-edge* *top-edge-2*) 

(•pOx* (- *pOx* *top-edge-2*)) 
(*pOy* (- *pOy* »top-edg3-2*)) 
(*depth* 0)) 
(do-arrows)))) ;Draw small arrows 

2. Stripe the head of the large arrow. We define a function, 
stripe-arrowhead, and call it from draw-big-arrow. The function loops to 
calculate the coordinates of the endpoints of the stripes, starting in the 
upper right corner and decrementing x and y by •stripe-distance*. 
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(defun draw-big-arrow () 

;; Determine coordinates of arrowhead vertexes 
(mu1t1p1e-va1ue-bind 

(•plx» 'ply* 'pZx* 'pSy* 'pSx* *p5y* «p6x» *p6y») 

(compute-arrowhead-polnts) 
;; Determine coordinates of shaft vertexes 
(nuUiple-value-bind (*p3x« *p3y» «p4x« 'pAy*) 
(compute-arrow-shaft-points) 
(draw-big-outline) ;0ut1ine arrow 

(when *do-the-stripes» 

(stripe-arrowhead))))) ;Str1pe head 



Function to control striping the head of each arrow. 
Determines coordinates of starting and ending points for each 
stripe. Calls DRAW-ARROWHEAD-LINES to draw each stripe, 
(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- «pOx* 'top-edge*) 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from »pOx« by »str1pe-distance» above last-x 

;; Find ending y-coord for each stripe, decrementing by 

;; distance between stripes. 

for end-y downfrom "pOy* by •stripe-distance* 

; ; Draw a stripe 

do (draw-arrowhead- lines start-x end-y))) 



Draws a stripe in an arrowhead. Arguments are the x-coord 
of the starting point and the y-coord of the ending point 
of a stripe, 
(defun draw-arrowhead-lines (start-x end-y) 

(send *dest* ':show-11nes start-x *pOy* *pOx* end-y)) 



3. Stripe the exposed portions of the shaft of the large arrow. The shaft 
consists of a series of descending triangles along the left and right sides. 
We define a function, stripe-big-arrow-shaft, to control the striping. We 
then define six functions, three to stripe the left side and three to stripe the 
right. The first function for each side iterates through the triangles that 
make up the shaft. The second function stripes one triangle. The third 
function draws one stripe. 
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(defun draw-big-arrow () 

;; Determine coordinates of arrowhead vertexes 
(multlple-value-blnd 

(*plx« «ply* *p2x« «p2y» «pSx» »p5y» »p6x» «p5y») 

(compute-arrowhead-points) 
;; Determine coordinates of shaft vertexes 
(multiple-valuG-blnd ('pSx* *p3y« •p4x« •p4y*) 
(computs-srrow-shaft-polnts) 
(draw-big-outline) ;0ut11ne arrow 

(when •do-the-str1pes» 

(stripe-arrowhead) ;Stripe head 

(stripe-big-arrow-shaft))))) ;Stripe shaft 



Function to control striping the shaft of the large arrow. 
Just calls STRIPE-BIG-ARROW-SHAFT-LEFT to stripe the left side 
and STRIPE-BIG-ARROW-SHAFT-RIGHT to stripe the right side, 
(defun stripe-big-arrow-shaft () 

(stripe-big-arrow-shaft- left) 

(stripe-big-arrow-shaft-right)) 



Function to control striping left side of big arrow's shaft. 
Iterates over the triangles that make up the shaft. Determines 
coordinates of the apex and bottom right point of each triangle. 
Calls DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT to stripe each triangle, 
(defun stripe-big-arrow-shaft-left () 

:; Set up a counter for depth. Don't exceed maximum recursion 

;; level. 

(loop for shaft-depth from below «max-depth* 

;; Find current top edge and its fractions 

for top-edge = 'top-edge* then (// top-edge 2) 

for top-edge-2 = (// top-edge 2) 

for top-edge-4 = (// top-edge 4) 

;; Find coordinates of apex of triangle 

for apex-x = »p2x» then (- apex-x top-edge-2) 

for apex-y = *p2y« then (- apex-y top-edge-2) 

;; Find x-coord of bottom right vertex 

for right-x = (+ apex-x top-edge-4) 

;; Find y-coord of bottom edge of triangle 

for bottom-y = (- apex-y top-edge-4) 

;; Stripe each triangle 

do (draw-big-arrow-shaft-stripes- left 

top-cdge-4 apex-x apex-y right-x bottom-y))) 
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stripes each triangle In left side of big arrow's shaft. 
Arguments are one-fourth current top edge, x- and y-coords 
of apex of triangle, x- and y-coords of bottom right vertex. 
Determines coordinates of starting and ending points for 
each stripe. Calls DRAW-BIG-ARROW-SKAFT-LINES-LEFT to 
draw the lines that make up each stripe, 
(defun draw-big-arrow-shaft-stripes-left 

(top-edge-4 apex-x apex-y right-x bottom-y) 
(loop with half-distance = (// »str1pe-distance» Z) 
;; Find x-coord of last stripe In triangle 
with last-x = (- apex-x top-edge-4) 

Find x-coord of top of each stripe, decrementing 
from the apex by HALF the horizontal distance 
between stripes. Stop at last stripe, 
for start-x from apex-x ty half-distance above last-x 
;; Find y-coord of top of stripe 
for start-y downfrora apex-y by half-distance 
;; Find x-coord of endpoint of stripe 
for end-x downfron right-x by »str1pe-distance» 
;: Draw a stripe 
do (draw-big-arrow-shaft-l ines-lef t 

start-x start-y end-x bottom-y))) 



Draws a stripe on the left side of the big arrow's shaft. 
Arguments are the coordinates of the starting and ending 
points of each stripe, 
(defun draw-big-arrow-shaft-lines-left 
(start-x start-y end-x end-y) 
(send «dest« ':show-lines 

start-x start-y end-x end-y)) 



Function to control striping right side of big arrow's shaft. 
Iterates over the triangles that make up the shaft. Determines 
coordinates of the top point of each triangle. Calls 
DRAW-BIG-ARROW-SHAFT-STRIPES-RIGHT to Stripe each triangle, 
(defun stripe-big-arrow-shaft-rioht () 

;; Set up a counter for depth. Don't exceed maximum recursion 
; ; level . 

(loop for shaft-depth from below 'inax-depth* 
;; Find new top edge and its fractions 
for top-edge = »top-edge« then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top- edge 4) 
;; Find coords of top point of triangle 
for start-x = (+ "pZx* top-edge-4) 
for top-y = (- *p2y* «top-edge-4*) 
then (- top-y top-edge-2 top-edge-4) 
;; Stripe the triangle 
do (draw-big-arrow-shaft-stripes-rlght 

top-edge-2 top-edge-4 start-x top-y))) 
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Stripes each triangle in right side of big arrow's shaft. 
Arguments are one-half and one-fourth of current top edge, and 
coords of top point of the triangle. Determines coordinates of 
starting and ending points for each stripe. Calls 
DRAW-BIG-ARROW-SHAFT-LINES-RIGKT to draw a stripe, 
(defun draw-blg-arrow-shaft-stripes-right 

(top-edge-2 top-edge-4 start-x top-y) 
(loop with half-distance = (// »stripe-d1stance» 2) 
;; Find y-coord of last stripe In triangle 
with last-y = (- top-y top-edge-2) 

;; Find y-coord of starting point of stripe. Don't go 
;; past the end of the triangle. 

for start-y from top-y by »str1pe-distance* above last-y 
;; Find coords of ending point of the strips, decrementing 
;; by HALF the horizontal distance between stripes 
for end-x downfroni (+ start-x top-edge-4) by half-distance 
for end-y downfroni (- top-y top-edge-4) by half-distance 
; ; Draw a stripe 

do (draw-big-arrow-shaft-lines-right 
start-x start-y end-x end-y))) 



Draws a stripe on the right side of the big arrow's shaft. 
Arguments are the coordinates of the starting and ending points 
of the stripe, 
(defun draw-big-arrow-shaft- lines-right 
(start-x start-y end-x end-y) 
(send 'dest* ':show-11nes 

start-x start-y end-x end-y)) 



4. Stripe the heads of the small arrows. We call stripe-arrowhead from 
draw-arrow. 



(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexss 
(multiple-value-blnd 

(•plx* »ply* «p2x* •p2y» 'pSx* »p5y« »p6x» *p6y«) 

(compute-arrowhead-points) 
(draw-outline) ;0utl1ne arrowhead 

(when •do-the-stripes» 

(stripe-arrowhead)))) ;Str1pa head 



, Stripe the exposed shafts of the small arrows. Like the shaft of the large 
arrow, these shafts are composed of a series of descending triangles. We 
define three functions: stripe-arrow-shaft iterates through the triangles 
that make up a shaft; draw-arrow-shaft-stripes stripes one triangle; and 
draw-arrow-shaft-iines draws one stripe. We call stripe-arrow-shaft from 
draw-arrow. 
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•p5y«) 



;0ut11ne arrowhead 



(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(mult1p1e-va1ue-b1nd 

(•plx« 'ply* 'pEx* 'pZy* 'pSx* 'pSy* 'pex* 

( compute-arrowhead-points } 
(draw-outline) 
(when »do-the-str1pes« 

(stripe-arrowhead) ;Str1pe head 

(stripe-arrow-shaft)))) jStrlpe shaft 

Function to control striping the shaft of a small arrow. 
Iterates over the descending triangles that make up the shaft. 
Calculates the coordinates of the top left and bottom right 
vertexes of each triangle. Calls DRAW-ARROW-SHAFT-STRIPES to 
stripe each triangle, 
(defun stripe-arrow-shaft () 

;; Set up a counter for depth. Don't exceed maximum 
;; recursion level. 

(loop for shaft-depth from 'depth* below *max-depth* 
;; Calculate fractions of new top edge 
for top-edge-2 = 'top-edge-Z* then (// top-edge-2 2) 
for top-edge-4 = (// top-edge-2 2) 
;; Find coords of top left point of triangle 
for left-x = *p2x» then (- left-x top-edge-4) 
for top-y = »p2y» then (- top-y top-edge-2 top-edge-4) 
;: Find coords of bottom right point of triangle 
for right-x = (+ left-x top-edge-2) 
for bottom-y = (- top-y top-edge-2) 
;; Stripe the triangle 
do (draw-arrow-shaft-strlpes 

left-x top-y rIght-x bottom-y))) 



;; Stripes each triangle In the shaft of a small arrow. 
; ; Arguments are coordinates of the top left and bottom 
;; right points of the triangle. Calculates the y-coord 
;; of the starting point and the x-coord of the ending point 
;; of each stripe. Calls DRAW-ARROW-SKAFT- LINES to draw the 
;; stripe, 
(defun draw-arrow-shaft-strlpes 

(left-x top-y right-x bottom-y) 
;; Find y-coord of starting point of stripe. Don't go 
;: below the bottom of the triangle. 

(loop for start-y from top-y by 'stripe-distance* above botton-y 
;; Find x-coord of ending point of the stripe 
for end-x downfrom right-x by 'stripe-distance* 
;; Draw a stripe 
do (draw-arrow-shaft-lines 

left-x start-y end-x bottom-y))) 
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;;; Draws a strips in tha shaft of a small arrow. Arguments are 
;;; the coordinates of the starting and ending points of the 
;;; stripe, 
(defun draw-arrow-shaft-lines 

(left-x start-y end-x bottora-y) 
(send 'dest* ':show-11nes 

left-x start-y end-x botton-y)) 

Figure 2 (page 29) shows the output of the program, with stripes of even spacing and thickness. 
This stage in program development differs from the beginning of the program in two ways: 

• As we add new functions, we need to refer to existing code for such 
information as the order of arguments in argument lists and the values of 
variables and constants (section 2.6, page 28). 

• We must start to change existing code, adding function calls and new 
arguments. These changes require increasing use of facilities for editing 
code (section 2.8, page 49). 

2.6 Finding Out About Existing Code 

When you write or edit programs, you often need to find characteristics of existing code. If 
you write programs incrementally, you need to find existing definitions, argument lists, and 
values. To maintain modularity, you must know how new code should interact with previously 
written modules. If you want to incorporate parts of the Lisp Machine system in your 
programs, you often have to refer to system source code. 

Zmacs and Zetalisp have many facilities for retrieving information about Lisp objects and for 
displaying and editing source code. This section describes features especially useful for writing 
and editing code. We discuss facilities for learning about Lisp objects, symbols, variables, 
functions, and pathnames. 

2.6.1 Objects 

describe displays information about a Lisp object in a form that depends 
on the object's type. For example, for a special variable, describe displays 
the value, package, and properties, including documentation, pathname of 
the source file, and Zmacs buffer sectioning node. 

An interactive, window-oriented version of descril)e is the Inspector (see 
section 4.7, page 94). 

describe does not display array elements. For that you can use the 
Inspector or listarray. 



Example 

(describe '«top-edge») 
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Figure 2. Program output with stripes of even spacing and density. 
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2.6.2 Symbols 



The value of »TOP-EDGE» is NIL 
*TOP-EDGE» is in the GRAPHICS package. 
*TOP-EDGE* has property DOCUMENTATION: 

■Length of the top edge of the arrow" 
•TOP-EDGE* has property SPECIAL: 

#<UMIX-PATHNAME "VIXEN: //dess//(loc//workstyles//pcodex.»"> 
#<UNIX-PATHNAME "VIXEN: //dess//doc//workstyles//pcodex.«">, 

an object of flavor FS: UNIX- PATHNAME, 

has instance variable values: 

FS:HOST: #<UNIX-CHAOS-HOST SCRC-VIXEN> 

FS:OEVICE: :UNSPECIFIC 

FS:DIRECTORY: ("dess" "doc" "workstyles") 

FS:NAME: "pcodex" 

FS:TYPE: NIL 

FS: VERSION: :UNSPECIFIC 

SI: PROPERTY-LIST: (BASE 10 :MODE ...) 

FS:STRING-F0R-PRINTIN6: "VIXEN: //dess//doc//workstyles//pcodex.«" 

FS:STRING-FOR-HOST: "//dess//doc//v«)rkstyles//pcodex.«" 

FS:STRING-FOR-EDITOR: NIL 

FS:STRING-FOR-DIRED: NIL 

FS:STRING-FOR-DIRECTORY: NIL 

•TOP-EDGE* has property SOURCE-FILE-NAME: 
((DEFVAR #<UNIX- PATHNAME 

"VIXEN: //dess//doc//worksty1es//pcodex.«">)) 
((DEFVAR #<UNIX-PATHNA«E 

"VIXEN: //dess//doc//worksty1es//pcodex .«">)) is a list 

•TOP-EDGE* has property ZWEI:ZMACS-BUFFERS: 

((DEFVAR #<SECTION-NODE Variable 'TOP-EDGE^ 27316607>)) 

((DEFVAR #<SECTION-KODE Variable •TOP-EDGE* 27316607>)) is a list 

•TOP-EDGE* 



Reference 

(describe object) Displays information about object in a 

form that depends on the object's 
type. For named structures, displays 
the symbolic names and contents of 
the entries in the structure. 

(listarray array) Returns a list whose elements are the 

elements of ivray. 



Several Zmacs commands and Lisp functions find the name of a symbol or 
retrieve information about it. Unless you specify a package, most of these 
commands search the global package and its inferiors. It now takes several 
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minutes to search all these packages; if you don't know which one the 
symbol is in, you might want to use functions like apropos and who-calls 
only as a last resort. (See Program Development Help Facilities for more on 
the meanings and default values of arguments to these functions.) 



Example 

In defining the function strlpe-big-arrow-shaft-left, we need to use the 
constant *max-depth*, but we remember only that its name contains 
"depth". We use either m-ESCRPE (to evaluate a form in the editor 
minibuffer) or SELECT L (to select a Lisp Listener) and then evaluate: 



(apropos "depth" 'graphics) 

GRAPHICS: DEPTH 

GRAPHICS :*MAX-DEPTH« - Bound 

GRAPHICS :SHAFT-DEPTH 

GRAPHICS :*DEPTH» - Bound 

(•DEPTH* SHAFT-DEPTH •MAX-DEPTH* DEPTH) 



Example 

After compiling stripe-arrowhead we want to test the program as written 

so far, but we forget which function calls draw-arrow-graphic: 

(who-calls 'draw-arrow-graph 1c 'graphics) 

DO-ARROW calls DRAW-ARROW-GRAPHIC as a function. 
(DO-ARROW) 

You can also find the callers of a function with List Callers (ro-X) (see 
section 2.6.4, page 33). 



Reference 

(apropos string package inferiors superiors) 

Displays the names of all symbols 
whose names contain string. Indicates 
whether or not the symbol is bound. 
Displays argument lists of functions. 

Where Is Symbol (m-X) Displays the names of packages that 

contain the specified symbol. 

(where-is string package) Displays the names of packages that 

contain a symbol whose print name is 
string. 

(who-calls symbol package inferiors superiors) 

Displays information about uses of 
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(what-files-call symbol packasii 



(pllst symbol) 



List Matching Symbols (m-X) 



symbol as function, variable, or 
constant. Returns a list of the names 
of callers of symbol. 

Displays names of files that contain 
uses of symbol as function, variable, 
or constant. 

Returns the list representing the 
property list of symbol. 

Displays the names of symbols for 
which a predicate lambda-expression 
returns something other than nil. 
Prompts for a predicate for the 
expression (lambda (symbol) 
predicate). By default, searches the 
current package; with an argument of 
c-U, searches all packages; with an 
argument of c-U c-U, prompts for 
the name of a package. Press c-. to 
edit definitions of symbols that satisfy 
the predicate. 



2.6.3 Variables 



Describe Variable At Point (c-sh-V) is a useful command to display 
information about a variable. It tells you whether or not the variable is 
bound, whether it has been declared special, and the file, if any, that 
contains the declaration. You can find the value of a variable by evaluating 
it in a Lisp Listener. If you have added a documentation string to the 
variable declaration, you can retrieve the string with c-sh-y or with 
c-sh-D, m-sh-D, or documentation (see section 2.6.4, page 33). 



Example 

In writing stripe-arrow-shaft we want to find out whether or not 

♦max-depth* is bound. c-sh-V displays the following information: 

•MAX-DEPTH* has a value and is declared special by file 
VIXEN: /dess/doc/workstyles/pcodex.1 
Number of levels of recursion 



Reference 

Describe Variable At Point (c-sh-V) Indicates whether or not the variable 

is declared special, is bound, or is 
documented by defvar or def const. 
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2.6.4 Functions 

Many Zmacs and Zetalisp facilities for finding out about functions apply 
both to functions defined by defun and to objects defined by other special 
forms and macros that begin with "def '. 

2.6.4.1 Definitions 

Edit Definition (m-.) is a powerful command to find and edit definitions of 
functions and other objects. It is particularly valuable for finding source 
code, including system code, that is stored in a file other than that 
associated with the current buffer. It finds multiple definitions when, for 
example, a symbol is defined as a function, a variable, and a flavor. It 
maintains a list of these definitions in a support buffer, where you can use 
m-. to return to the definitions even when you are finished editing. 

Section 5.2.2 (page 129) describes how to use Edit Definition (m-.) to edit 
definitions of flavor methods. 



Example 

We have written stripe-arrowhead and want to call it from 

draw-big-arrow. We use m-. to position the cursor at the definition of 

draw-big-arrow. 

Reference 

Edit Definition (m-. ) Selects a buffer containing a function 

definition, reading in the source file if 
necessary. You can specify a 
definition by typing the name into the 
minibuffer or clicking on a name 
already in the buffer. Offers name 
completion for definitions already in 
buffers. With a numeric argument, 
selects the next definition satisfying 
the most recently specified name. 

2.6.4.2 Names 

Often you know only part of a function name and need to find the 
complete name. Use Function Apropos (m-X). 

Example 

We want to call stripe-arrowhead from draw-arrow, but we remember 
only that draw-arrow contains the string "arrow". We use Function 
Apropos (m-X) to display the names of functions that contain "arrow". We 
click left on the name draw-arrow to edit its definition. 
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m-X Function Apropos arrow 

Functions matching arrow: 

DO-ARROW 

DO-ARROWS 

DRAW-ARROW 

DRAW-ARROW-GRAPHIC 

DRAW-ARROWHEAD-LINES 

DRAW-BIG-ARROW 

ORAW-BIG-ARROW-SHAFT-LINES-LEFT 

DRAW-BIG-ARROW-SHAFT-LINES-RIGHT 

ORAW-BIG-ARROW-SHAFT-STRIPES-LEFT 

DRAW-BIG-ARROW-SHAFT-STRIPES-RIGHT 

STRIPE-ARROWHEAD 

STRIPE-BIG-ARROW-SHAFT 

STRIPE-BIG-ARROW-SHAFT-LEFT 

STRIPE-BIG-ARROW-SHAFT-RIGHT 



Reference 

Function Apropos (m-X) Displays the names of functions that 



contain a string. Press c-. or click 
left on names in the display to edit 
the definitions of the functions listed. 



2.6.4.3 Documentation 

Function definitions can include documentation strings. When you need to 
know the purpose of the function, you can retrieve the documentation with 
c-sh-D, m-sh-D, or documentation. 

Example 

We wrote a long source-code comment at the beginning of the definition of 
draw-arrow-graphic. We could have made this comment a documentation 
string: 
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(defun draw-arrow-graphic (*top-edge* 'pOx* 'pOy*) 

"Function controlling the calculation module. 
Controls calculation of the coordinates of the endpolnts of the lines 
that make up the figure. The three arguments are the length of the top 
edge and the coordinates of the top right point of the large arrow. 
DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow and then 
calls DO-ARROWS to draw the smaller ones.* 
(let (('top-edge-Z* (// «top-edge« 2)) 
(•top-edge-4» (// *top-edge* 4)) 

;; Compute horizontal distance between stripes in the 
large arrow, assuming 64 stripes in the large 
arrowhead, 
(•stripe-distance* (// 'top-edge* 64))) 
(draw-big-arrow) ;Draw large arrow 

;; Length of the top-edge for the first small arrow is half the 
;; length for the large arrow. Bind new coordinates for the top 
;; right point of the small arrow, 
(let ((«top-edge* •top-edge-2«) 

(•pOx* (- 'pOx* »top-edge-2«)) 
(*pOy» (- «pOy* *top-edge-2«)) 
{♦depth* 0)) 
(do-arrows)))) ;Oraw small arrows 

Later, when defining do-arrow, we add a call to draw-arrow-graphic. We 
want to be sure that this is the control function for the calculation module. 
We position the cursor at the name draw-arrow-graphic inside the 
definition of do-arrow and use m-sh-D to display the documentation string 
for draw-arrow-graphic: 

DRAW-ARROW-GRAPHIC: ("TOP-EDGE* 'POX* 'POY*) 

Function controlling the calculation module. 

Controls calculation of the coordinates of the endpoints of the lines 

that make up the figure. The three arguments are the length of the top 

edge and the coordinates of the top right point of the large arrow. 

DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow and then 

calls DO-ARROWS to draw the smaller ones. 

c-sh-D displays the first line of the documentation string: 
DRAW-ARROW-GRAPHIC: Function controlling the calculation module. 

To ensure that c-sh-D displays meaningful information, make the first line 
of each documentation string a complete sentence that summarizes the 
function. 

Reference 

Brief Documentation (c-sh-D) Displays the first line of the 

function's documentation string. 
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Long E>ocumentation (la-sh-D) Displays the function's documentation 

string. 

(documentation function) Displays the function's documentation 

string. 

2.6.4.4 Argument Lists 

Quick Arglist (c-sh-fl) and arglist retrieve the argument list for a 
function. What these facilities display depends on the nature of the 
function, whether or not it has been compiled, and what options the 
function includes; see the Lisp Machine Manual, section 10.9, page 150, and 
Program Development Help Facilities for details. 

Example 

We are editing the definition of do-arrow to add a call to 
draw-arrow-graphic. We want to see the argument list for 
draw-arrow-graphic. We position the cursor at the name 
draw-arrow-graphic in the definition of do-arrow and use c-sh-R: 

DRAW-ARROW-GRAPKIC: (*TOP-EDGE» 'PCX* *POY*) 



Reference 

Quick Arglist (c-sh-R) Displays a representation of the 

argument list of the current function. 
With a numeric argument, you can 
type the name of the function into 
the minibuffer or click on a function 
name in the buffer. 

(arglist function) Displays a representation of the 

function's argument list. 

2.6.4.5 Callers 

When you change a function definition, you sometimes need to make 
complementary changes in the function's callers. Four Zmacs commands 
find the callers of a function. These commands, Uke who-calls, now take 
several minutes to search all packages for callers. (For the example 
program, we need to search only the graphics package.) By default, these 
commands search the current package. With an argument of c-U, they 
search all packages. You can specify the packages to be searched by giving 
the commands an argument of c-U c-U. 

Example 

We decide to change the order of the arguments to draw-arrow-graphic. 
We want to be sure to change all the callers of draw-arrow-graphic to call 
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the function with arguments in the correct order. We use Edit Callers 
(m-X). 



Reference 
List Callers (m-X) 



Multiple List Callers (m-X) 



Edit Callers (m-X) 



Multiple Edit Callers (m-X) 



Lists functions that call the specified 
function. Press c-. to edit the 
definitions of the functions listed. 

Lists functions that call the specified 
functions. Continues prompting for 
function names until you press only 
RETURN. Press c-. to edit the 
definitions of the functions listed. 

Prepares for editing the definitions of 
functions that call the specified 
function. Press c-. to edit 
subsequent definitions. 

Prepares for editing the definitions of 
functions that call the specified 
functions. Continues prompting for 
function names until you press only 
RETURN. Press c-. to edit subsequent 
definitions. 



2.6.5 Pathnames 

Zmacs provides several ways of finding the name of a file. If you just need 
the name of a file and have some idea what directory it is in, you can use 
c-X c-D with an argument of c-U or View Directory (m-X) to display a 
directory. If you want to operate on files in a directory, you can use c-X D 
with an argument of c-U or Dired (m-X) to edit a directory. If you want 
to find a source file but don't know what directory it is in, you might 
remember the name of a function defined in the file. In that case, you 
might be able to use m-. to find the file. 

Example 

After editing the definitions in the calculation module, we want to find the 
output module to edit the definition of do-arrow. We forget the name of 
the file, but we remember the name of the directory. We can use c-U c-X 
c-D to display the directory. If we have interned do-arrow or read its file 
into a buffer, we can use m-. to find do-arrow directly. 



Reference 

Display Directory (c-X c-D) 



Displays the current buffer's file's 
directory. With an argument of c-U, 
prompts for a directory to display. 
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View Directory (m-X) Lists a directory. 

tr Dired (c-X D) Edits the current buffer's file's 

directory. With an argument of c-U, 
prompts for a directory to edit. 
Displays the files in the directory. 
You can use single-character 
commands to operate on the files. 

Dired (m-X) Edits a directory. Displays the files 

in the directory. You can use single- 
character commands to operate on the 
files. 

2.7 Program Development: Refinlrtg Stripe Density and Spacing 

At this stage of development, the program outlines the arrows in the figure and fills them with 
stripes of uniform thickness and spacing. In the finished figure, stripe thickness or density 
increases from upper right to lower left within each arrow, and stripe spacing varies among the 
levels of the figure. We adjust the stripe spacing by replacing the constant distance between 
stripes by a variable. We correct the stripe density by drawing multiple adjacent lines for each 
stripe. 

We adjust the stripe spacing in three steps: 

1. Define a variable, •strlpe-d*, to represent the distance between stripes for 
each arrow. 

(defvar 'stripe-d* nil 

"Horizontal distance between stripes for each arrow*) 

2. Calculate the value of *stripe-d* for each arrow. For the large arrow, this 
is just •stripe-distance*. For the small arrows, we need to call a new 
function, conipute-stripe-d, from draw-arrow, compute-stripe-d calculates 
•stripe-d* as a fraction of *stripe-distance* that depends on the level of 
recursion. It ensures that *stripe-d* divides *top-edge* evenly and that 
♦stripe-d* is never less than 3. 
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(defun draw-big-arrow () 

; ; Determine coordinates of arrowhead vertexes 
(mu1t1p1e-va1ue-b1nd 

(•plx* 'ply* •p2x» «p2y» "pSx* *p5y» »p6x* «p6y») 

(cotnpute-arrowtiead-polnts) 
: ; Determine coordinates of shaft vertexes 
(multlple-value-blnd ('pSx* *p3y* •p4x« •p4y») 
(compute-arrow-shaft-polnts) 
(draw-blg-outHne) ;0ut11ne arrow 

(when •do-the-str1pes* 

;: Bind distance between stripes 
(let (("strlpe-d* "stripe-distance*)) 

(stripe-arrowhead) :Str1pe head 

(str1pe-b1g-arrow-shaft)))))) ;Str1pe shaft 

(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(inu1t1p1e-va1ue-b1nd 

(•plx* "ply* *p2x* 'pSy* 'pSx* *p5y* *p6x* *p6y*) 

(compute-arrowhead-points) 
(draw-outline) ;0ut11ne arrowhead 

(when *do-the-str1pes* 

;; Calculate distance between stripes 
(let (('strlpe-d* (compute-str1pe-d))) 

(stripe-arrowhead) ;Str1pe head 

(stripe-arrow-shaft))))) ;Str1pe shaft 
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Calculates horizontal distance between stripes. 
Distance is a fraction of the distance between stripes for the 
large arrow. The divisor depends on the level of recursion. 
Distance divides length of top edge evenly when possible to 
maintain continuity between head and shaft of arrow, 
(defun compute-stripe-d () 

;; Distance should be at least 3 pixels so that there is some 
:: white space between lines, 
(if (s »stripe-distance* 3) 
3 

;; First find a fraction of »STRIPE-DISTANCE» that depends 
;; on recursion level 

(loop for dist = (fixr (// *stripe-distance* 

(selectq 'depth* 
(0 2) 
(14) 
(2 2) 
(3 1.5) 
(4 1.5) 

(otherwise 2)))) 
;; Increment if it doesn't divide •TOP-EDGE* evenly 
then (1-f dist) 

when (= (\ *top-edge* dist)) 
;; Stop when no remainder. Don't return a value 
;; less than 3. 
do (return (if (S dist 3) 3 dist))))) 

3. Replace •stripe-distance* with *stripe-d* in the functions 
Stripe-arrowhead and draw-arrow-shaft-stripes. 



(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- *pOx« »top-edge*) 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from *pOx* by «stripe-d* above last-x 

;; Find ending y-coord for each stripe, decrementing by 

;; distance between stripes. 

for end-y downfrom "pOy* by *str1pe-d* 

; ; Draw a stripe 

do (draw-arrowhead-lines start-x end-y))) 
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(defun draw-arrow-shaft-stripes 

(left-x top-y r1ght-x bottora-y) 
;; Find y-coord of starting point of stripe. Don't go 
;; below the bottom of the triangle. 
I (loop for start-y from top-y by •str1pe-d» above bottom-y 

;; Find x-coord of ending point of the stripe 
I for end-x downfrom right-x by *stripe-d* 

;; Draw a stripe 
do (draw-arrow-shaft-lines 

left-x start-y end-x bottom-y))) 

We adjust the stripe density in three steps: 

1. Define two new constants for each. arrow, *dll* and •d2*. *dl* represents 
the stripe density, or the proportion of the distance between stripes that is 
black, at the upper right of each arrow. *d2» represents the density at 
lower left for each arrow. We estimate *dl* to be 0.15 and •d2* to be 
0.75. 

I (def const «dl» 0.15 

I "Proportion of distance between upper right stripes that is bl; k") 

(defconst *d2» 0.75 

"Proportion of distance between lower left stripes that 1s black") 

2. Define a function, compnte-nlines, that returns the number of adjacent 
lines that make up a stripe to be drawn. This function calls another, 
compnte-dens, to calculate the proportion of the distance between stripes 
that is black. This proportion is a function of the position of the stripe 
between the upper right and lower left of the arrow, compnte-nlines 
multiplies this proportion by *stripe-d* to determine the number of lines 
that make up the stripe. This number must be at least one and less than 
•stripe-d* minus one. 

The argument to compute-nlines represents the horizontal position of the 
stripe to be drawn between the upper right and lower left of the arrow. 
Imagine the top edge of each arrow projected to the left beyond the 
arrowhead. Imagine each stripe projected to the upper left until it 
intersects with the extended top edge. The argument to compnte-nlinss is 
the x-coordinate of this intersection. 'pOx* is the x-coordinate of this 
intersection for the top right corner of each arrow, where the stripe density 
is 'dl*. *x2* is the x-coordinate of this intersection for the lower left 
stripe in each arrow, where the density is *d2*. The x-coordinate for each 
stripe must be between *pOx» and «x2*, and the density must be between 
•dl* and •d2*. 

(defvar »x2« nil 

"X-coordinate of projection of lower left stripe on top edge") 
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(defun draw-big-arrow () 

; ; Determine coordinates of arrowhead vertexes 
(niu1t1p1e-va1ue-b1nd 

(•plx* »ply« 'pZx* •p2y« 'pSx* 'pSy* «p6x» *p6y«) 

(compute-arrowhead-points } 
;; Determine coordinates of shaft vertexes 
(multlple-value-blnd («p3x» 'pSy* •p4x« •p4y«) 
(compute-arrow- shaft-points) 
(draw-big-outline) ;0ut11ne arrow 

(when «do-the-str1pes» 

;: Bind distance between stripes and x-coord of 
;: projection of last stripe onto top edge 
(let ((*str1pe-d« »str1pe-distance») 

(•xZ» (- "pOx* 'top-edge* *top-edge«))) 
(stripe-arrowhead) ;Str1pe head 

(str1pe-b1g-arrow-shaft)))))) ;Stripe shaft 

(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(mu1tip1e-va1ue-bind 

(»plx« »ply» »p2x» "pZy* »p5x« »p5y* »p6x« 'pCy*) 

(compute-arrowhead-points) 
(draw-outline) ;0ut1ine arrowhead 

(when «do-the-stripes« 

;; Calculate distance between stripes and x-coord of 
;; projection of last stripe onto top edge 
(let ((«stripe-d* (compute-str1pe-d)) 

(»x2* (- *pOx* «top-edge» «top-edge*))) 
(stripe-arrowhead) ;Stripe head 

(stripe-arrow-shaft))))) ;Str1pe shaft 



Calculates the number of lines that compose each stripe. 
Calls COMPUTE-DENS to calculate the proportion of distance 
between stripes to be filled, then multiplies by the actual 
distance between stripes. Hakes sure that there Is at least 
one line and that there aren't too many lines to leave some 
white space, 
(defun compute-nllnes (x) 

;; Call COMPUTE-DEMS and multiply result by 'stripe-d* 
(let ((nl (fix (* »stripe-d» (computa-dens x))))) 
;; Supply at least one line 
(cond (($ nl 1) 1) 

;; But leave some white space between lines 
((i nl (- 'stripo-d* 1)) (- »str1pe-d« 2)) 
(t nl)))) 
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Calculates proportion of distance filled In between each stripe. 
The argument Is the x-coordlnate of the projection of the current 
stripe onto the line formed by the top edge. Determines where the 
projection of the current stripe Is on this line in relation to the 
distance from first to last stripes in the arrow. Multiplies this 
fraction by the difference between densities of first and last 
stripes. Finally, adds the density of the first stripe, 
(defun compute-dens (x) 
(+ »dl« (« (- 'dZ* »dl«) 

(// (- X »pOx») (float (- *xZ* »pOx»)))))) 



3. For each function that draws a stripe, replace the sending of one 
:show-lines message by a loop that might send several Determine the 
number of messages each function should send by calling compute-niines. 



(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- *pOx* »top-edge*) 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from »pOx* by •stripe-d* above last-x 

;; Find ending y-coord for each stripe, decrementing by 

;; distance between stripes. 

for end-y downfrom 'pOy* by 'stripe-d* 

;; Find number of lines in the stripe 

for nlines = (compute-niines start-x) 

;: Draw the lines that make up the stripe 

do (draw-arrowhead- lines nlines start-x end-y last-x))) 



(defun draw-arrowhead-lines (nlines start-x end-y last-x) 
: ; Set up a counter 
(loop for 1 from below nlines 

;; Find starting x-coord, subtracting counter from first 

; ; x-coord 

for first-x = (- start-x 1) 

; ; Hake sure we don't go past the end of the arrowhead 

while « last-x first-x) 

; ; Draw a line 

do (send *dest* *:show-lines 

first-x 'pOy* »pOx» (- end-y 1)))) 
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(defun stripe-big-arrow-shaft-left () 

;; Set up a counter for depth. Don't exceed maximum recursion 

; ; 1 eve 1 . 

(loop for shaft-depth from below 'tnax-depth* 

;; Find current top edge and its fractions 

for top-edge = 'top-edge* then (// top-edge 2) 

for top-edge-2 = (// top-edge 2) 

for top-edge-4 = (// top-edge 4) 

;; Find coordinates of apex of triangle 

for apex-x = »p2x« then (- apex-x top-edge-2) 

for apex-y = •p2y» then (- apex-y top-edge-2) 

;; Find x-coord of bottom right vertex 

for right-x = (+ apex-x top-edge-4) 

;; Find y-coord of bottom edge of triangle 

for bottom-y = (- apex-y top-edge-4) 

;; Find the x-coord of the projection of the first 

;; stripe onto top edge 

for xoff = (- «pOx» 'top-edge*) then (- xoff top-edge) 

;; Stripe each triangle 

do (draw-big-arrow-shaft-stripes- left 

top-edge-4 apex-x apex-y right-x bottcm-y xoff))) 

(defun draw-big-arrow-shaft-stripes- left 

(top-edge-4 apex-x apex-y right-x bottom-y xoff) 
(loop with half-distance = (// »stripe-distance« 2) 
;; Find x-coord of last stripe in triangle 
with last-x = (- apex-x top-edge-4) 
;; Find x-coord of top of each stripe, decrementing 
:; from the apex by HALF the horizontal distance 
;; between stripes. Stop at last stripe, 
for start-x from apex-x by half-distance above last-x 
;; Find y-coord of top of stripe 
for start-y downfrom apex-y by half-distance 
;; Find x-coord of endpoint of stripe 
for end-x downfrom right-x by "stripe-distance* 
;: Find number of lines In the stripe 
for nlines ^(compute-n lines (- xoff (- right-x end-x))) 
; ; Draw a stripe 
do (draw-big-arrow-shaft-lines-left 

nlines start-x start-y end-x bottom-y last-x))) 
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(defun draw-b1g-arrow-shaft-11nes-1eft 

(nllnes start-x start-y end-x end-y last-x) 
;; Set up two counters -- wa need to draw two lines at once 
(loop for 1 from 

for 12 from by 2 

;; Find x-coord of top of first line in stripe 
for first-x = (- start-x i) 
;; Don't exceed number of lines in stripe 
while (< i2 nlines) 

;; Don't go past the end of the triangle 
while (< last-x firs\-x) 
; ; Draw a line 

do (send »dest» ':show-11nes first-x (- start-y 1) 
(- end-x 12) end-y) 
Draw a second line. The two lines are a refinement 
to stagger the endpoints of the lines so the diagonal 
edge looks neat, 
(send "dest* ':show-1ines first-x (- start-y 1 1) 
(- end-x 12 1) end-y))) 



(defun stripe-b1g-arrow-shaft-r1ght () 

;; Set up a counter for depth. Don't exceed maximum recursion 

; ; 1 eve 1 . 

(loop for shaft-depth from below «max-depth* 

;; Find new top edge and its fractions 

for top-edge = "top-edge* then (// top-edge 2) 

for top-edge-2 = (// top-edge 2) 

for top-edge-4 = (// top-edge 4) 

;; Find coords of top point of triangle 

for start-x = (+ •p2x» top-edge-4) 

for top-y = (- »p2y» *top-edge-4*) 

then (- top-y top-edge-2 top-edge-4) 

;; Find x-coord of projection of first stripe onto 

;: top-edge 

for xoff = (- »pOx« »top-edge*) then (- xoff top-edge) 

;; Stripe the triangle 

do (draw-big-arrow-shaft-stripes-right 

top-edge-2 top-edge-4 start-x top-y xoff))) 
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(defun draw-b1g-arrow-shaft-stripes-right 

(top-edge-2 top-edge-4 start-x top-y xoff) 
(loop with half-distance = {// *stripe-distance* 2) 
;; Find y-coord of last stripe In triangle 
with last-y = (- top-y top-edge-2) 

;; Find y-coord of starting point of stripe. Don't go 
;; past the end of the triangle. 

for start-y froai top-y by •strips-distance* above last-y 
;; Find coords of ending point of the stripe, decrementing 
;; by HALF the horizontal distance between stripes 
for end-x downfrom (+ start-x top-edge-4) by half-distance 
for end-y downfrom (- top-y top-edge-4) by half-distance 
;; Find number of lines that make up the stripe 
for nlines = (compute-nlines (- xoff (- top-y start-y))) 
;; Draw a stripe 
do (draw-big-arrow-shaf t-1 1nes-r ight 

nlines start-x start-y end-x end-y last-y))) 



(defun draw-big-arrow-shaft- lines-right 

(nlines start-x start-y end-x end-y last-y) 
;; Set up two counters -- we need to draw two lines at once 
(loop for i from 

for 12 from by 2 

;; Find y-coord of ending point of line 
for stop-y = (- end-y i) 

;; Don't exceed number of lines in the stripe 
while (< 12 nlines) 

;; Don't go past the bottom of the triangle 
while (< last-y stop-y) 
; ; Draw a line 

do (send «dest« ':show-11nes start-x (- start-y 12) 
(- end-x 1) stop-y) 
Draw a second line. The two lines are a refinement 
to stagger the endpolnts of the lines so the diagonal 
edge looks neat, 
(send »dest« ':show-lines start-x (- start-y 12 1) 
(- end-x 1 1) stop-y))) 



Program Development Tools and Techniques 



47 



Symbolics. Inc. 



(defun stripe-arrow-shaft () 

;; Set up a counter for depth. Don't exceed maximum 

;: recursion level. 

(loop for shaft-depth from 'depth* below »max-depth* 
;; Calculate fractions of new top edge 
for top-edge-2 = "top-edga-J* then (// top-edge-2 2) 
for top-edge-4 » (// top-edga-2 2) 
;; Find coords of top left point of triangle 
for left-x = »p2x« then (- left-x top-edge-4) 
for top-y = «p2y« then (- top-y top-edse-2 top-edge-4) 
;; Find coords of bottom right point of triangle 
for right-x = (+ left-x top-edge-2) 
for bottom-y = (- top-y top-edge-2) 

;; Find x-coord of projection of first stripe onto top edge 
for xoff = (- «pOx» »top-edge«) 
then (- xoff top-edge-2 top-edge-2) 
;; Stripe the triangle 
do (draw-arrow-shaft-stripes 

left-x top-y right-x bottom-y xoff))) 



(defun draw-arrow-shaft-stripes 

(left-x top-y right-x bottom-y xoff) 
;; Find y-coord of starting point of stripe. Don't go 
;; below the bottom of the triangle. 

(loop for start-y from top-y by »stripe-distance9 above bottom-y 
;; Find x-coord of ending point of the stripe 
for end-x downfrom right-x by «stripe-d» 
;; Find number of lines in the stripe 
for nlines = (compute-nlines (- xoff (- right-x end-x))) 
;; Draw a stripe 
do (draw-arrow-shaft-lines 

nlines left-x start-y end-x bottom-y))) 

(defun draw-arrow-shaft- lines 

(nlines left-x start-y end-x bottom-y) 
;; Set up a counter. Don't exceed number of lines in the stripe, 
(loop for i from below nlines 

;; Find x-coord of ending point of the line 
for last-x = (- end-x i) 

;; Don't go past the left edge of the triangle 
while (< left-x last~x) 
;; Draw a line 

do (send 'dest* ':show-lines left-x (- start-y i) 
last-x bottom-y))) 



Figure 3 (page 48) shows the output of the program with stripes of varying spacing and 
thickness. 

At this stage in developing the program we define new functions, constants, and variables. But 
most of the work consists of changing existing code. Often you need to make similar changes 
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Figure 3. Program output with stripes of varying spacing and density. 
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to several functions: you add an argument or replace sending one message by a loop that sends 
several. In this case we are refining a new program, but when maintaining existing code you 
must also make selective or global changes. The most helpful Lisp Machine facilities are those 
for finding out about existing code (section 2.6, page 28) and for editing code (section 2.8, 
page 49). 

2.8 Editing Code 

The features we discussed in sections 2.2 (page 7) and 2.4 (page 19) are useful mainly in 
composing new code. The features we described in section 2.6 (page 28) are helpful in both 
writing and editing code. In this section we discuss features that are likely to be most useful in 
editing existing code. 

2.8.1 Identifying Changed Code 

Two pairs of List and Edit commands find or edit changed definitions in 
buffers or files. By default, the commands find changes made since the file 
was read; use numeric arguments to find definitions that have changed since 
they were last compiled or saved. 

Example 

After defining the routine that calculates the number of lines that compose 
each stripe, we changed many functions to call that routine and draw the 
appropriate number of lines. We want to look over the changes before 
recompiling the edited definitions. We use Edit Changed Definitions Of 
Buffer (m-X). 

Reference 

List Changed Definitions Of Buffer (m-X) 

Lists definitions in the buffer that 
have changed since the file was read. 
Press C-. to edit the definitions 
listed. 

Edit Changed Definitions Of Buffer (m-X) 

Prepares for editing definitions in the 
buffer that have changed. Press c-. 
to edit subsequent definitions. 

List Changed Definitions (m-X) Lists definitions in any buffer that 

have changed since the files were 
read. Press c-. to edit the 
definitions listed. 

Edit Changed Definitions (m-X) Prepares for editing definitions in any 

buffer that have changed. Press c-. 
to edit subsequent definitions. 

Print Modifications (m-X) Displays lines in the current buffer 
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Source Compare (m-X) 



Source Compare Merge (ra-X) 



that have changed since the file was 
read. 

Compares two buffers or files, listing 
differences. 

Compares two buffers or files and 
merges differences into a buffer. 



2.8.2 Searching and Replacing 

Many of the facilities discussed in section 2.6 (page 28), particularly the 
series of List and Edit commands, are useful for displaying and moving to 
code you wish to edit. The commands we discuss here find and replace 
strings. Tags tables offer a convenient means of making global changes to 
programs stored in more than one file. Use Select All Buffers As Tag 
Table (m-X) to create a tags table for all buffers read in. Use Select System 
As Tag Table (m-X) to create a tags table for all files in a system. (For 
information on systems, see the Lisp Machine Manual, chapter 24, page 406.) 



Exampie 

We have defined ♦stripe-d*, and we want to replace some occurrences of 
the constant ♦stripe-distance* by the variable *strlpe-d*. We use Query 
Replace (m-?.) to find each occurrence of *stripe-distance*. By pressing 
SPACE, we replace ♦stripe-distance* by *stripe-d* in functions like 
stripe-arrowhead. By pressing RUBOUT, we leave ♦stripe-distance* in place 
in functions like draw-big-arrow-shaft-stripes-left. 



Reference 

List Matching Lines (m-X) 



Incremental Search (c-S) 



Reverse Search (c-R) 



Displays the lines (following point) in 
the current buffer that contain a 
string. 

Prompts for a string and moves 
forward to its first occurrence in the 
buffer. Press c-S to repeat the 
search with the same string. Press 
c-R to search backward with the 
same string. After you invoke the 
command, if c-S is the first character 
you type (instead of a string), uses 
the string specified in the previous 
search. 

Prompts for a string and moves 
backward to its last occurrence in the 
buffer. Press c-R to repeat the 
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Tags Search (m-X) 
Replace (c-X) 

Query Replace (m-/!) 



Tags Query Replace (m-X) 



search with the same string. Press 
c-S to search forward with the same 
string. After you invoke the 
command, if c-R is the first character 
you type (instead of a string), uses 
the string specified in the previous 
search. 

Searches for a string in all files listed 
in a tags table. 

In the buffer, replaces all occurrences 
(following point) of one string by 
another. 

In the buffer, replaces occurrences 
(following point) of one string by 
another, querying before each 
replacement. Press HELP for possible 
responses. 

In files listed in a tags table, replaces 
occurrences of one string by another, 
querying before each replacement. 



Select All Buffers As Tag Table (ra-X) 



Select System As Tag Table (m-X) 



Creates a tags table for all buffers in 
Zmacs. 

Creates a tags table for files in a 
system defined by defsystem. 



2.8.3 Moving Text 



2.8.3.1 Moving through Text 

To move short distances through text, you can use the Zmacs commands for 
moving by lines, sentences, paragraphs. Lisp forms, and screens, or you can 
click left to move point to the mouse cursor. To move longer distances, you 
can move to the beginning or end of the buffer or use the scroll bar. To go 
to another buffer, use Select Buffer (c-X B). To switch back and forth 
between two buffers, use Select Previous Buffer (c-ro-L). 

Suppose you want to record a location of point so that you can return to 
that location later. Two techniques are particularly useful: 

• Store the location of point in a register. Use Save Position (c-X S) to store 
point in a register. Use Jump to Saved Position (c-X J) to return to that 
location. 

• Use m-SPflCE to push the location of point onto the mark stack. Later, you 
can use c-m-SPflCE to exchange point and the top of the mark stack. c-U 
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c-SPflCE pops the mark stack; repeated execution moves to previous marks. 
Note: Some Zmacs commands other than c-SPfiCE push point onto the 
mark stack. When point is pushed onto the mark stack, the notification 
"Point pushed" appears below the mode Une. 



Reference 

Select Buffer (c-X B) 



Select Previous Buffer (c-m-L) 



Save Position (c-X S) 



Moves to another buffer, reading the 
buffer name from the minibuffer. 
With a numeric argument, creates a 
new buffer. 

Moves to the previously selected 
buffer. 

Stores the position of point in a 
register. Prompts for a register name. 



Jump To Saved Position (c-X J) 



Moves point to a position stored in a 
register. Prompts for a register name. 



Set Pop Mark (c-SPfiCE) 



Push Pop Point Explicit (m-SPfiCE) 



With no argument, sets the mark at 
point and pushes point onto the mark 
stack. With an argument of c-U, 
pops the mark stack. 

With no argument, pushes point onto 
the mark stack without setting the 
mark. With an argument n, 
exchanges point with the nth position 
on the mark stack. 

Move To Previous Point (c-m-SPRCE) Exchanges point and the top of the 

mark stack. 



Swap Point And Mark (c-X c-X) 



Exchanges point and mark. Activates 
the region between point and mark. 
Use Beep (c-G) to turn off the 
region. 



2.8.3.2 Killing and Yanking 

When you need to repeat text, you usually want to copy it rather than type 
it anew. The most common facilities for copying text are the commands for 
killing and yanking. Commands that kill more than one character of text 
push the text onto the kill ring. c-Y yanks the last kill into the buffer. 
After a c-Y command, m-Y deletes the text just inserted, yanks the previous 
kill, and rotates the kill ring. 
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Example 

In the function draw-big-arrow-shaft-llnes-left, we send two :show-lincs 
messages on each iteration. The purpose is to arrange the starting points of 
the lines along the diagonal edge so that they lie as closely as possible on a 
45-degree line. The second send expression is nearly identical to the first. 
Instead of typing a new expression, we copy and edit the first one. We 
follow these steps: 

1. Position the cursor after the close parenthesis that ends the first send 
expression. 



(def un draw-big-arrow-shaft-1 Inas-lef t 

(nlines start-x start-y end-x end-y last-x) 



do (send 'dest* ':show-lines first-x (- start-y 1) 
(- end-x 12) end-y) 

2. Use c-m-RUBOUT to kill the send expression and push it onto the kill ring. 

(defun draw-b1g-arrow-shaft-l1nes-1ef t 

(nlines start-x start-y end-x end-y last-x) 



do 

3. Use c-Y to restore the expression. 

(defun draw-b1g-arrow-shaf t-1 ines-left 

(nlines start-x start-y end-x end-y last-x) 

do (send 'dest* ':show-l1nes first-x (- start-y i) 
(- end-x 12) end-y) 

4. Use LINE to move to the next line and indent. 

5. Use c-Y to insert a copy of the send expression. 

(defun draw-blg-arrow-shaft-llnes-left 

(nlines start-x start-y end-x end-y last-x) 



do (send "dest* ': show- lines first-x (- start-y i) 

(- end-x 12) end-y) 
(send 'dest* ':show-11nes first-x (- start-y 1) 

(- end-x 12) end-y) 
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6. Edit the second send expression. 



(defun draw-big-arrow-shaft-1 Ines-left 

(nllnes start-x start-y end-x end-y ]ast-x) 



do (send 'dest* ':show-11nes f1rst-x (- start-y 1) 

(- end-x 12) end-y) 
(send «dest« ': show- lines first-x (- start-y 11) 

(- end-x 12 1) end-y))) 



Example 

Suppose we have an existing program in which we have already defined the 

function compute-nlines. We can copy the function in three ways: 

• Use c-m-K or c-m-RUBOUT to kill the definition. Use c-Y to restore it. Go 
to the new buffer. Use c-Y to insert a copy of the definition. 

• Use c-m-H to mark the definition. Use m-W to push it onto the kill ring. 
Go to the new buffer. Use c-Y to uisert a copy of the definition. 

• Click middle on the first or last parenthesis of the definition to mark the 
definition. Click double-middle to push it onto the kill ring. Move to the 
new buffer. Click double-middle to insert a copy of the definition. 



Reference 

Kill Sexp (c-m-K) Kills forward one or more Lisp 

expressions. 

Backward Kill Sexp (c-n-RUBOUT) Kills backward one or more Lisp 

expressions. 



Mark Definition (c-m-H) 
Save Region (m-W) 
Yank (c-Y) 



Yank Pop (m-Y) 



Puts point and mark around the 
current definition. 

Pushes the text of the region onto the 
kill ring without killing the text. 

Pops the last killed text from the kill 
ring, inserting the text into the buffer 
at point. With an argument n, yanks 
the nth entry in the kill ring. Does 
not rotate the kill ring. 

After a c-Y command, deletes the 
text just inserted, yanks previously 
killed text from the kill ring, and 
rotates the kill ring. Repeated 
execution yanks previous kills and 
rotates the kill ring. 
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[Region (M2)] 



When region is defined, pushes the 
text of region onto the kill ring 
without killing the text (like m-U). 
Repeated execution has the following 
effects: 

• First repetition: kills the text of 
region, pushing the text onto the kill 
ring (like c-W) 

• Second repetition: pops the text of 
region from the kill ring, inserting the 
text into the buffer at point (like 
c-Y) 

• Third and subsequent repetitions: 
delete the text just inserted, yank 
previously killed text from the kill 
ring, and rotate the kill ring (like 
m-Y) 

If no region is defined, pops the last 
killed text from the kill ring, inserting 
the text into the buffer at point (like 
c-Y). Repeated execution deletes the 
text just inserted, yanks previously 
killed text from the kill ring, and 
rotates the kill ring (like m-Y). 



2.8.3.3 Using Registers 



Using c-Y and m-Y to copy text can become tedious when you have to 
rotate through a long kill ring to find the text you need. Another method, 
especially useful when you want to copy a piece of text more than once, is 
to save and restore the text using registers. 



Reference 

Put Register (c-X X) 



Open Get Register (c-X G) 



Copies contents of the region to a 
register. Prompts for a register name. 

Inserts contents of a register into the 
current buffer at point. Prompts for 
a register name. 



2.8.3.4 Copying Buffers and Files 

Use Insert File (m-X) to place the contents of an entire file in your buffer. 
You can copy the contents of a buffer in two ways: 
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Use Insert Buffer (m-J^), naming the buffer you want to copy. 
Use c-X H to mark the buffer you want to copy. Use m-U to push its text 
onto the kill ring. Move to the new buffer. Use c-Y to insert a copy of 
the text. 



Reference 

Mark Whole (c-X H) 

Insert Buffer (m-X) 



Insert File (m-X) 



Marks an entire buffer. 

Inserts contents of the specified 
buffer into the current buffer at 
point. 

Inserts contents of the specified file 
into the current buffer at point. 



2.8.4 Keyboard Macros 

Sometimes you need to perform a uniform sequence of commands on several 
pieces of text. You can save keystrokes by converting the sequence to a 
keyboard macro and installing it on a single key. If you anticipate using a 
macro often, you can write Lisp code to define it in an init file. If you 
frequently use particular extended commands, install them on single keys 
with Set Key (m-X). 



Reference 

Start Kbd Macro (c-X () 

End Kbd Macro (c-X ) ) 

Call Last Kbd Macro (c-X E) 
Name Last Kbd Macro (m-X) 

Install Macro (m-X) 

Install Mouse Macro (m-X) 



Deinstall Macro (m-X) 



Set Key (m-X) 



Begins recording keystrokes as a 
keyboard macro. 

Stops recording keystrokes as a 
keyboard macro. 

Executes the last keyboard macro. 

Gives the last keyboard macro a 
name. 

Installs on a key the last keyboard 
macro or a named macro. 

Installs a keyboard macro on a mouse 
click (such as 12). When you click 
to call the macro, point moves to the 
position of the mouse cursor before 
the macro is executed. 

Deinstalls a keyboard macro from a 
key or a mouse click. 

Installs an extended command on a 
single key. Use HELP C to look for 
unassigned keys. 
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2.8.5 Using Multiple Windows 

2.8.5.5 Multiple Buffers 

Sometimes when editing you move often between two buffers. You might 
want to see the two buffers at the same time rather than switch between 
them. A conmion use of multiple-window display is to edit source code 
while viewing compiler warnings (see section 4.1, page 71). 



Example 

We add a new :show-lines message to the program but forget what 
arguments the message takes. We want to display the source code for the 
message handler on the same screen as our program code. We use c-X 2 to 
create another window and move to it. We use Edit Methods (m-X) to find 
the source code for the method that handles :s!iow-lines (see section 5.2.2, 
page 129). 



Example 

After finishing the program, we collect a file of bug reports from users. We 
want to use these reports in correcting our program code. We create two 
windows, one displaying the program code and the other the bug-report file. 
We edit the program code, using c-m-V to scroll the bug-report window as 
we correct each bug. 



Reference 

Split Screen (m-X) 



Two Windows (c-X 2) 
View Two Windows (c-X 3) 

Modified Two Windows (c-X 4) 

Other Window (c-X 0) 
Scroll Other Window (c-m-V) 
One Window (c-X 1) 



Pops up a menu of buffers and splits 
the screen to display the buffers you 
select. 

Creates a second window, with the 
current buffer on top and the 
previous buffer on the bottom. Puts 
the cursor in the bottom window. 

Creates a second window, vsrith the 
current buffer on top and the 
previous buffer on the bottom. Puts 
the cursor in the top window. 

Creates a second window and visits a 
buffer, file, or tag there. Displays the 
current buffer in the top window. 

Moves to the other of two windows. 

Scrolls the other of two windows. 

Returns to one-window display, 
selecting the buffer the cursor is in. 
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2.8.5.6 Zmacs and Other Windows 

Use [Split Screen] or [Edit Screen] from a system menu to display an editor 
window on the screen with other kinds of windows. 

Example 

In testing new program functions, we want to have the current version of 
the figure on the same screen as the program code. We use [SpUt Screen] 
from a system menu to add a Lisp Listener to the screen. We move 
between windows by clicking left on the window to which we want to 
move. 

We evaluate (pkg-goto 'graphics) and then (do-arrow) in the Lisp 
Listener. We adjust the arguments to draw-arrow-graphic so that the 
arrow fits neatly into the Lisp Listener window. 

(defun do-arrow () 

(let ((»dest« (make-instance 'screen-arrow-output))) 
(send terminal-lo ':c1ear-screen) 
(draw-arrow-graphic 640 1300 1850))) 

Figure 4 (page 59) shows the appearance of the screen with graphic output 
in a Lisp Listener and source code in a Zmacs buffer. 

To return to displaying only the Zmacs window, we use [Split Screen] with 
the existing Zmacs buffer as the only element. 

Reference 

[Split Screen / Lisp / Existing Window / Existing Zmacs Buffer / Do It] 

(from a system menu) 
Adds a Lisp Listener to a screen 
displaying an existing Zmacs buffer. 

[Split Screen / Existing Window / Existing Zmacs Buffer / Do It] (from a 

system menu) 

Resumes one-window display of an 
existing Zmacs buffer. 

2.8.5.7 Other Displays 

The window system allows you to use menus, choose-variable-values 
windows, and other multiple-window displays in executing programs. See 
Introduction to Using the Window System and Lisp Machine Choice Facilities 
for details. See chapter 5 (page 101) for examples of simple uses of 
windows, including choose-variable-values windows. 
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Hap Listener 2 



Calculates the nunber of lines that conpose each stripe. 
Calls COMPUTE-DENS to calculate the proportion of distance 
between stripes to be filled, then nultlplles by the actual 
distance between stripes. Hakes sure that there is at least 
one line and that there aren't too nany lines to leave sone 
white space, 
(defun conpute-nllnes (x) 

;! Call COMPUTE-DENS and multiply result by «STRIPE-D* 
(let ((nl (fix (« «stripe-d« (conpute-dens x))))) 
;; Supply at least one line 
(cond Hi nl 1) 1) 

;; But leave sone white space between lines 
((i nl (- tstripe-dt 1)) (- tstr1pe-d« 2)) 
(t nl)))) 

Calculates proportion of distance filled in between each stripe. 
The argunent is the x-coordinate of the projection of the current 
stripe onto the line forned by the top edge. Deternines where the 
projection of the current stripe is on this line In relation to the 
distance fron first to last stripes in the arrow. Multiplies this 
fraction by the difference between densities of first end last 
stripes. Finally, adds the density of the first stripe. 
(defun conpute-dens (x) 
(♦ «dl« (» (- »d2« «dl») 

(// (- X «p0x«) (float (- »x2* »p0x«)))))) 



ZMflCS (LISP) pcodex.l /dess/doc/workstyles/ UIXEN: « [More above and below] 



.:Move point, L2:Move to point, MtMark thing, M2:Saue/K111/yank, R:Menu, R2:Systen nenu 



B8/'17/'e3 18:06:25 ron 



GRAPHICS! Ty 



?: 



Figure 4. Using multiple windows to test the program while viewing the source code. 
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3. Compiling and Evaluating Lisp 

When should you compile code, and when evaluate it? 

The main job of the compiler is to convert interpreted functions into compiled functions. An 
interpreted function is a list whose first element is lambda, named-lambda, subst, or 
named-subst. These functions are executed by the Lisp evaluator. The most common 
interpreted functions you define are named-lambdas. V/hen you load a source file that 
contains def an forms or when you otherwise evaluate these forms, you create named-lambda 
functions and define the function specs named in the forms to be those functions. 

Compiled functions are Lisp objects that contain programs in the Lisp Machine instruction set 
(the machine language). They are executed directly by the microcode. Compiling an 
interpreted function (by calling the compiler on a function spec) converts it into a compiled 
function and changes the definition of the function spec to be that compiled function. 

You seldom compile functions directly. Instead, you compile either regions of Zmacs buffers or 
source files. 

• Compiling a region of a Zmacs buffer (or the whole buffer) causes the 
compiler to process the forms in the region, one by one. This processing has 
side effects on the Lisp environment. We summarize the compiler's actions 
in section 3.1.1 (page 62). 

• CompiUng a source file translates it into a binary file. With some 
exceptions, this processing does not have side effects on the Lisp 
environment at compile time. When you load a compiled file that defines 
functions, you create compiled rather than interpreted functions and define 
function specs to be those compiled functions. In other respects, loading a 
compiled file has essentially the same effects as loading a source file 
(evaluating the forms in the file). We discuss compiling files in section 3.1.2 
(page 65). 

Most Symbolics programmers compile all their program code. The compiler checks extensively 
for errors and issues warnings that help detect bugs like typographical errors, unbound symbols, 
and faulty Lisp syntax. Compiled code runs faster and takes up less storage than interpreted 
code. You can compile code in portions and decide at compile time whether or not to save the 
compiler output in a binary file. 

The most common use for interpreted functions is stepping through their execution. You 
cannot step through the execution of a compiled function. If a function is compiled, you can 
read its definition into a Zmacs buffer, evaluate the definition, and then step through a 
function call. 

In addition to evaluating definitions to create interpreted functions, you might need to evaluate 
forms to test a program or find information about a Lisp object. (Unless you are using the 
Stepper, functions that you call during these evaluations are usually compiled.) You can 
evaluate a form in a Lisp Listener, a breakpoint loop, or the minibuffer. 

See the Lisp Machine Manual, chapter 10, page 136, for more information on functions. 
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3.1 Compiling Lisp Code 

You can use Ztnacs commands to compile code in a file or Zmacs buffer. Most Symbolics 
programmers compile code as soon as they have written enough to test. This practice lets them 
correct errors quickly and produce simple working versions of programs before adding more 
complex operations. A common command for incremental compiling from a Zmacs buffer is 
Compile Region (c-sh-C). If no region is defined, this command compiles the current 
definition. 

In addition to compiling definitions as they write them. Symbolics programmers consider it 
good practice to recompile a function soon after effecting a change. Because recompiling a 
series of functions or an entire program can be time-consuming, it is easier and faster to make 
changes and then use a single command to recompile only the changed functions. Using 
Compile Changed Definitions Of Buffer (m-sh-C) or Compile Changed Definitions (m-X) is 
easier in this case than recompiling each function separately or recompiling the entire buffer. 

The order in which you compile definitions can be important. For example, suppose you have 
a function that binds a variable you want to be treated as special. If you compile the function 
definition before compiling the variable declaration, the compiler treats the variable as local 
and generates incorrect output. For this reason you should usually put defvar and defconst 
forms at the beginning of a file or into a separate file to be compiled and loaded before 
function definitions. 

When editing a program, it is a good idea to load the entire program before you start work on 
it. When you compile new definitions or recompile edited ones, the compiler will have access 
to variable declarations, macros, functions, and other information. You will also be able to use 
Zmacs commands and Lisp functions for finding information about other parts of the program 
(see section 2.6, page 28). 

Sometimes when you compile a file, write large sections of code at once, or make many changes 
to a large program, compiling the code produces many warning messages. Chapter 4 (page 71) 
describes how Edit Compiler Warnings (m-X) lets you use the compiler warnings as a reference 
source for debugging. 

See the Lisp Machine Manual, chapter 16, page 197, for more information on the compiler. 

3.1 .1 Compiling Code in a Zmacs Buffer 

Compiling a top-level form in a Zmacs buffer — using a command like 
Compile Region (c-sh-C) or Compile Buffer (m-X) — has side effects on 
the Lisp environment. Following is a summary of the compiler's actions: 

Form Action 

Macro form If the form is a list whose first element is a 

macro, the compiler expands the form and 
processes this expanded form instead of the 
original. 

Function definition If the form is a list whose first element is defun, 
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Macro definition 



Special case 



Atom, comment form 
Other 



the compiler constructs a lambda-expression from 
the definition, converts the lambda-expression into 
a compiled function, and defines the function spec 
named in the definition to be that compiled 
function. 

If the form is a list whose first element is macro, 
the compiler constructs a lambda-expression as the 
macro's expander function, converts the lambda- 
expression into a compiled function, and defines 
the function spec named in the definition to be 
the macro. A defmacro form expands into this 
kind of form. 

Some forms, like eval-vhen, declare, and 
progn 'compile forms, have special meaning for 
the compiler. It handles each of these in a 
different way. (See the Lisp Machine Manual, 
chapter 16, page 197, for details.) 

The form is ignored. 

The form is evaluated. 



Example 

We have written some initial code for the controlling function of the 

calculation module: 



(defvar «top-edge* nil 

"Length of the top edge of the arrow") 

(defvar 'pOx* nil 

"X-coordinate of point 0") 

(defvar *pOy» nil 

"Y-coordinate of point 0") 

(defun draw-arrow-graphic (»top-edge* »pOx •pOy») 

(let ((•top-edge-2* (// 'top-edge* 2)) 

(»top-edge-4» (// nop-edge* 4))) 
(draw-big-arrow))) 



Because we have no other code in the buffer, we can compile these 
definitions using Compile Buffer (m-X). If we had more code in the buffer, 
we could compile these definitions by setting the mark at one end and point 
at the other and using Compile Region (c-sh-C). 

The compiler displays the following warnings: 
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For Function DRAW-ARROW-GRAPHIC 

The variable •TOP-EDGE-4* was never used. 
The variable •TOP-EDGE-2* was never used. 
The variable *POX was never used. 

The following functions were referenced but don't seem defined: 
DRAW-BIG-ARROW referenced by DRAW-ARROW-GRAPHIC 

The first set of warnings indicates that the compiler is treating 
*top-edge-2«, ♦top-edge-4*, and ♦pOx as local variables. We neglected to 
declare *top-edge-2» and ♦top-edge-4* special with defvar; *pOx is of 
course a misspelling. The lack of a definition for draw-big-arrow is not 
surprising; we have yet to write that definition. 

We add the two defvars and correct the spelling of *pOx«. We compile the 
changes using Compile Changed Definitions Of Buffer (m-sh-C). The 
compiler now displays only one warning: 

The following functions were referenced but don't seem defined: 
DRAW-BIG-ARROW referenced by DRAW-ARROW-GRAPHIC 

We continue writing the program by defining draw-blg-arrow. 



Reference 

Compile Region (c-sh-C) Compiles the region. If no region is 

marked, compiles the current 
definition. 

[Zmacs Window / Compile Region] Compiles the region. If no region is 

marked, compiles the current 
definition. 

Compile Changed Definitions Of Buffer (m-sh-C) 

Compiles all the definitions in the 
current Zmacs buffer that have 
changed since the definitions were last 
compiled. 

Compile Changed Definitions (m-X) Compiles all the definitions in any 

Zmacs buffer that have changed since 
the definitions were last compiled. 

Compile Buffer (m-X) Compiles the current Zmacs buffer. 

Compile (m-X) [Zmac* Window (R)] Pojs up a menu of options for 

compiling code in the current context. 
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3.1.2 Compiling and Loading a File 

Compiling a file, using Compile File (m-X) or cooipller:compile-file, saves 
the compiler output in a binary file of canonical type :bln. For the most 
part, compiling a file does not have side effects on the Lisp environment. 
The basic difference between compiling a source file and compiling the same 
forms in a buffer is this: When you compile a file, most function specs are 
not defined and most forms (except those within eval-when (compile) 
forms) are not evaluated at compile time. Instead, the compiler puts 
instructions into the binary file that cause these things to happen at load 
time. You can load a source or binary file into the Lisp environment by 
using Load File (m-X) or load. You can compile a file and then load the 
resulting binary file by using compilericompUe-file-load. 



Example 

In a previous session, we wrote the output routines for the program, saved 

them in a file, and compiled that file. Now we are writing the first 

calculation routines, and we want to test them. We need to load the file 

that contains the compiled code for the output routines. We use Load File 

(m-X). 

Suppose our two files are in the directory >Symbol,lcs>examples> on Lisp 
Machine acme-blue. The file containing the output routines is arrow-out. 
The current Zmacs buffer, and the file containing the calculation module, is 
arrow-calc. When we type m-X load file (or m-X 1o f, using completion), 
Zmacs prompts for a file name: 

Load File: (Default Is ACME-BLUE:>Symbo1ics>exaiiiples>arrow-calc) 

We type arrow-out, without a file type. The latest version of 
arrow-out.bin is loaded. If no compiled version exists or if the latest 
compiled file is older than the latest source file, Zmacs offers to compile the 
source file and then load the compiled version. 



Reference 

Compile File (m-X) Prompts for the name of a file and 

compiles that file, placing the 
compiled code in a file of canonical 
type :bin. 

(compiler:compile-file file-name) Compiles a file, placing the compiled 

code in a file of canonical type :bin. 

Load File (m-X) Prompts for a file name, taking the 

default from the current buffer. 
Offers to save the buffer if it has 
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changed since the file was last read or 
saved. Offers to compile the source 
file if no compiled version exists or if 
the source file was created after the 
latest compiled version. If you specify 
a file type, loads the latest version of 
the file of that type. If you don't 
specify a file type, loads the latest 
version of the binary file (even if 
older than the latest source file); if no 
binary file exists, loads the latest 
source file. 

(load file-name) Loads a file into the Lisp 

environment. If you specify a file 
type, loads the latest version of the 
file of that type. If you don't specify 
a file type, loads the latest version of 
the binary file (even if older than the 
latest source file); if no binary file 
exists, loads the latest source file. 

(compilencompiie-file-load file-name) 

Compiles a file, placing the compiled 
code in a file of canonical type :bin. 
Loads the resulting binary file. 



3.2 Evaluating Lisp Code 



3.2.1 Evaluation and the Editor 

The most common reason for evaluating definitions in a Zmacs buffer is to 
step through the execution of the functions they define. Sometimes in 
debugging you want to proceed step by step through a function call, using 
step or the :step option to trace (see section 4.4.2, page 86). You can do 
this only with interpreted functions. If a function is compiled, you can use 
Edit Definition (m-.) to read its definition into a Zmacs buffer. You can 
then evaluate the definition using Evaluate Region (c-sh-E). When you 
have finished stepping, you can recompile the definition. 

The evaluation of Lisp forms in the editing buffer or the minibuffer 
normally displays the returned values in the echo area (Iseneath the mode 
line near the bottom of the screen). Any output to standard-output during 
the evaluation appears in the editor typeout window. Two commands. 
Evaluate Into Buffer (m-X) and Evaluate And Replace Into Buffer (m-X), 
print the returned values in the Zmacs buffer at point. With a numeric 
argument, these commands also insert any typeout from the evaluation into 
the Zmacs buffer. 
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Often while editing you need to evaluate forms other than definitions in a 
buffer. You need to call a function to test your program, or you need to 
call a function like describe to find information about a Lisp object. (Of 
course, these functions need not be interpreted.) You can type forms to be 
evaluated in three ways: 

• Use m-ESCflPE to evaluate a form in the minibuffer. 

• Use SUSPEND to enter a Lisp breakpoint loop. You type forms that are 
read in the buffer's package and evaluated. Use RESUME to return to the 
editor. 

• Use SELECT L or [Lisp] from a system menu to select a Lisp Listener and 
evaluate forms there. Use SELECT E or [Edit] from a system menu to 
return to the editor. 



Example 

We have found a bug in the program and suspect that it lies in the function 
do-arrows. We want to step through a call to that function, but it is 
compiled. We use Edit Definition (ra-.) to find the definition of do-arrows 
and Evaluate Region (c-sh-E) to evaluate the definition. We then step 
through a function call (see section 4.4.2, page 86). 

Example 

We have written and compiled the output routines and the initial code for 
the calculation module. We want to test the program as written so far. 
The top-level function to call is do-arrow. We can test the program in 
three ways: 

• Press m-ESCflPE and evaluate (do-arrow). The graphic output appears in a 
typeout window. We press SPACE to restore the editing buffer to the 
screen. 

• Press SUSPEND to enter a Lisp breakpoint loop and evaluate (do-arrow) 
there. We press RESUME to return to the editor. 

• Press SELECT L to select a Lisp Listener. If the current package is not 
graphics, we first evaluate (pkg-goto 'graphics) and then (do-arrow). We 
press SELECT E to return to the editor. 



Example 

We want to be sure that new function names do not conflict with other 
symbol names in the graphics package. Most of our function names 
contain the string "arrow". We want to find the symbol names that contain 
that string. We use m-ESCRPE, SUSPEND, or SELECT L and evaluate: 

(apropos "arrow" 'graphics) 
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Reference 

Evaluate Region (c-sh-E) 



Evaluates the region. If no region is 
marked, evaluates the current 
definition. 



Evaluate Changed Definitions Of Buffer (m-sh-E) 

Evaluates all the definitions in the 
current Zmacs buffer that have 
changed since the definitions were last 
evaluated. 



Evaluate Changed Definitions (m-X) 

Evaluate Buffer (m-X) 
Evaluate Into Buffer (m-X) 



Evaluates all the definitions in any 
Zmacs buffer that have changed since 
the definitions wttt last evaluated. 

Evaluates the current Zmacs buffer. 

Prompts for a Lisp form to evaluate 
and prints the returned values in the 
Zmacs buffer at point. 

Evaluate And Replace Into Buffer (m-X) 

Evaluates the Lisp form following 
point and replaces it with the printed 
representation of the values it returns. 



Evaluate Minibuffer (m-ESCflPE) 



Evaluate (tft-X) [Zmacs Window (R)] 



SUSPEND 



Prompts for a Lisp form to evaluate 
in the minibuffer and displays the 
returned values in the echo area. 

Pops up a menu of options for 
evaluating code in the current 
context. 

Enters a Lisp breakpoint loop, where 
you can evaluate forms. The current 
package in the breakpoint loop is the 
same as in the previous context. Use 
RESUME to return to the previous 
context. 



3.2.2 Lisp Input Editing 

When typing to a Lisp Listener you can use many editing commands to 
modify a form before you evaluate it. You often repeat the same function 
calls or variations of similar function calls when testing code. Instead of 
retyping these forms, you can use the Lisp input editor's ring of input 
entries to retrieve them within the same Lisp Listener. When you yank a 
previous form, the Lisp input editor places the cursor at the end of the form 
but omits the final close parenthesis or carriage return. You can then edit 
the form before typing the final delimiter to evaluate it. 
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Example 

We execute our program by calling the function do-arrow. We evaluate 
(do-arrow) once and would like to evaluate it again within the same Lisp 
Listener. We press c-C to yank the last form we typed. If that is not 
(do-arrow), we press m-C until (do-arrow appears, without the close 
parenthesis. We type a close parenthesis to begin the evaluation. 

Reference 

c-C Yanks the last form typed to the Lisp 

Listener. Excludes the final delimiter, 
allowing you to edit the form before 
evaluating it. With an argument n, 
yanks the nth form in the input ring. 
(This command is not available in 
Zmacs.) 

m-C After a c-C command, deletes the 

form just inserted, yanks the previous 
form from the input ring, and rotates 
the input ring. Repeated execution 
yanks previous forms and rotates the 
input ring. (This command is not 
available in Zmacs.) 
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4. Debugging Usp Programs 

The Lisp Machine offers a variety of tools for debugging Lisp programs. The kind of 
debugging aid you use depends on the application of the program. Bugs might be more obvious 
in a graphics program than in a minor modification of some internal system function. 
Problems with a graphics programs are sometimes evident from the program's output. On the 
other hand, programs with a complex window system application might have bugs that are 
difficult to identify. 

Debugging aids are more appropriate for some kinds of bugs than for others. You commonly 
encounter three sorts of problems with a program: 

• The program does not compile correctly. You can use the compiler 
warnings database to edit code before recompiling. 

• The program compiles, but running it signals an error. Usually errors 
invoke the Debugger, where you can examine stack frames, return values, 
disassemble code, call the editor, and perform other tasks. 

• The program runs but does not behave as it should. You can use many 
techniques for Hnding the problem, including commenting out sections of 
code, tracing, stepping, setting breakpoints, disassembling, and inspecting. 
Often the most effective method is simply studying the source code. 

4.1 The Compiler Warnings Database 

The compiler sometimes produces many warning messages. The compiler maintains a database 
of these messages, organized by file. Each time you compile or recompile code, the compiler 
adds or removes warnings from the database, so that the database reflects the state of your 
program as of the last time you compiled it. 

If you want to save warnings in a file, you can use Compiler Warnings (m-X) to put them in a 
buffer and then write them to a file. When you make a system using make-system, you can 
use the :batch option to save compiler warnings in a file (see the Lisp Machine Manual, 
section 24.3, page 411). Use Load Compiler Warnings (m-X) to load compiler warnings into 
the database from a file. 

If compiler warnings exist in the database. Edit Compiler Warnings (m-X) lets you edit source 
code while consulting the corresponding warnings. The command splits the screen, with 
compiler warnings in one window and the source code to which the warnings apply in the 
other. As you finish editing each section of code, you press c-. . This displays the next 
warning in one window and the source code to which the next warning applies in the other 
window. When you reach the last compiler warning, pressing c-. returns the screen to its 
previous configuration. 



Example 

In section 3.1.1 (page 62), we discussed compiling the initial code for the 
calculation module of the sample program. Figure 5 (page 72) shows the 
result of using Edit Compiler Warnings (m-X) after compiling the buffer 
with the initial code. The compiler warnings are in the upper window and 
the source code in the lower window. 
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Warnings for file UIXEH: /dess/doc^uorksty I es^pcodex . t 

■ For Function DRfiU-flRROW-GRRPHIC 

The variable «T0P-EDGE-4» uas newer used. 
The variable »T0P-EDGE-2« uas never used. 
The variable *PSX uas never used. 
DRflW-BIG-RRROU uas referenced but not defined. 



♦Conpl ler-Harnlngs-l* 

(defun drau-arrou-graphic (stop-edge* «p8»< «pBy«) 
(let ((«top-edge-2« (// »top-edge« 2)) 
(«top-edge-4« (// *top-edge« 4))) 
( drau-b I g-arrou ) ) ) 



pcodex.l •dess/doc/uorkstyles/ VIXEN; 



ZMflCS (LISP) pcodex.l /dess/'docXuorkstyles/' UIXEN: « 
Control-. Is now Edit uarnings for next function. 
1 nore definition as uell 
Point pushed 

.:ttoue point, lSiMovc to point, M:Mark thing, MSrSave/KI I l/Vank, R:«cnu, R2:Systen neriu 



08/20/83 16:49:52 ron GRHPHICS: Tyl 



g, n2:5j 
fiPHICS: 



Figure 5. Edit Compiler Warning (m-X) splits the screen. The upper window contains 
compiler warnings. The lower window contains the source code. 
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Reference 

Edit Compiler Warnings (m-X) 



Compiler Warnings (m-X) 



Load Compiler Warnings (m-X) 



Prepares to edit all source code that 
has produced compiler warnings. 
Lists each file whose code produced 
warnings and asks whether you want 
to edit that file. Splits the screen, 
with compiler warnings in the upper 
window and source code that 
produced those warnings in the lower 
window. Use C-. to display 
subsequent warnings and edit the 
applicable code. 

Puts compiler warning messages into a 
buffer and selects that buffer. 

Loads a file containing compiler 
warning messages into the compiler 
warnings database. 



4.2 The Debugger 

Some errors during execution automatically invoke the Lisp Machine's Debugger. You can 
enter the Debugger at other times by pressing c-cn-SUSPEND. You can also enter the Debugger 
from within a program by inserting a call to dbg (with no arguments) into the code and 
recompiling. You can force a process into the Debugger by calling dbg with an argument of 
process. (See section 4.5, page 89.) 

The Debugger is useful for examining stack frames. With Debugger commands, you can see 
the arguments for the current stack frame, disassemble its code, return a value from it, go up 
and down the stack, and invoke the editor to edit function definitions. A common Debugger 
sequence is to disassemble code for the current frame, call the editor to edit and recompile the 
function, and test the changed function. 

A window-oriented version of the Debugger is the Display Debugger. Invoke it from within 
the Debugger by pressing c-m-U. 



Example 

We use the variable ♦x2» in computing the thickness of each stripe. *x2* is 
the x-coordinate of the projection of the last stripe in each arrow onto the 
top edge. We must bind it for each arrow to the difference between the 
value of •pOx* and twice the value of •top-edge*. 

Suppose that we forget to bind *x2* for the big arrow in the function 
draw-big-arrow. The initial value of *x2* is nU. In the function 
compute-dens, we subtract *pOx* from *x2*. Because the value of *x2* is 
not a number, we generate an error when we first call the function. The 
error invokes the Debugger with the name of the function in which the 
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error occurred, the value of the function's arguments, and the following 
error message: 

»Trap: The first argument given to SYS: --INTERNAL, NIL, was not a number. 

The Debugger also displays a listing of proceed types, special commands, and 
restart handlers, along with their key bindings (see Signalling and Handling 
Conditions, section 10.5, page 41). We can use one of these options, or we 
can use other Debugger commands to examine or manipulate the stack. 
^ Let's use c-m-U to invoke the Display Debugger. 

Figure 6 (page 76) shows the Display Debugger frame as it looks when we 
invoke it. The top window, an inspect pane, shows disassembled code for 
compute-dens with an arrow at the instruction that produced the error. 
The next window is an inspect history pane. The two windows side by side 
show the function's arguments and local variables and their values. The 
next window is a backtrace of the stack with an arrow at the frame that 
produced the error. The next window is a mouse-sensitive listing of options 
for proceeding or restarting. Next is a command menu. The bottom 
window is a Lisp Listener with the error message displayed. 

The disassembled code for compute-dens shows that the first argument to 
the subtraction that caused the error was the value of *x2*. We can 
inspect *%1* simply by clicking on its printed representation in the 
disassembled code. Figure 7 (page 77) shows the Display Debugger after we 
inspect *x2*. The value of •x2» is nil. We could have confirmed this by 
evaluating 'xZ* in the Lisp Listener pane. 

Now, if we remember what the value of *x2* is supposed to be, we can set 
•x2* to that value by typing to the Lisp Listener pane: 

(setq 'xZ* (- 'pOx* »top-edge* 'top-edge*)) 

We can then click on [Retry] to reinvoke the stack frame and continue the 
program. 

If we forget the value of •x2*, we might want to look at the source code. 
We can invoke the editor by clicking on [Edit] and then on the name of the 
function we want to edit. Inside the editor, we can change and recompile 
code. We can edit draw-big-arrow to bind ♦x2* and then recompile that 
function. If we entered the Debugger from the editor, we cannot return to 
the Debugger, but we can run the program again. Otherwise, we can return 
to the Display Debugger by pressing c-2. We can then set the value of 
*x2* and reinvoke the frame. 

In the Debugger, c-HELP displays information on Debugger commands. Following are some of 
the most useful commands: 
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Reference 

c-fl 

c-E 



c-L 

c-N 
c-P 
c-R 
m-B 
m-L 

c-ffi-R 
c-in-14 



Shows arguments for the current stack frame. 

Calls the editor to edit the function from the current 
frame. 

Clears the screen and redisplays the original error 
message. 

Goes down the stack by one frame. 

Goes up the stack by one frame. 

Returns a value from the current frame. 

Shows a backtrace of function names with arguments. 

Shows local variables and disassembled code for the 
current frame. 

Reinvokes the current frame. 

Invokes the Display Debugger. 



4.3 Commenting Out Code 



Sometimes a program runs but behaves in an unexpected way. In looking for the source of the 
problem, you might want to execute some portions of the program and disable others. An easy 
way to disable code without destroying it is to make a comment of it. You can comment out 
code by preceding it with a semicolon or surrounding it with #| and |#. 

Example 

We have outlined the large arrow and the largest of the small arrows. We 
try to outline the rest of the small arrows by adding two recursive function 
calls to do-arrows: 
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McT4 abcv* 
COMPUTE-DEMS 

3 PUSH-INDIRECT «D1« 

4 BUILTIM — IMTERHflL STOCK 

5 PUSH-LOCAL FP|8 ;K 

6 PUSH-IMDIRECT »P0X« 

7 BUILT I M — IHT ERHflL STHCK 
le PUSH-IMDIRECT iBS^ 

11 PUSH-INDIRECT tPBHi 

12 BUILTIM —INTERNAL STACK 

13 BUILTIN FLOAT STACK 

14 BUILTIN /-INTERNAL STACK 



«<8tack-Frane COHPUTE-DENS PC=12> 



Args: 

Ars a (K): 1888 



Loca I s : 



Mort abov* 
(DO-ARROU) 

(ORAU-ARROU-GRAPHIC 1288 1888 1888) 
(DRAU-BIG-ARROU) 
(STRIPE-ARROUHEAD) 
(COHPUTE-NLIHES 1808) 
•♦(CONPUTE-DENS 18B0) 

Moz* bttow 



Return to nornal debugger, staying In error context . 

Supply replacenent argunent 

Return a value fron the — INTERNAL Instruction 

Retry the — INTERNAL Instruction 

Lisp Top Lev/el in Lisp Listener 1 



What Error Inspect Return Set arg Retry T 
flrglist Edit Throw Search NIL 



>>Trap: The first argunent given to SYS: — INTERNAL, NIL, uas not a nunber. 



ilhoose a value by pointing at the value. Right gets object Into error handler. 
08/28/83 17:81:23 ron GRflPHICS: Tyl 



Figure 6. The Display Debugger: inspecting the stack frame containing a call to 
compute-dens. 
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«X2* 

Value Is NIL 

Funct I on Is unbound 

Property list: (DOCUriEMTflTIOM ". 

Package: XPackage GRRPHICS 3663S277> 



Top of obi*et 



SPECIRL IXUNIK-PflTHNflnE 'VIXEN: //'dess/'/workstyles« 



Bottom ofobi*et 



«<Stack-Frane COMPUTE-DENS PC=12> 
*X2« 



Rros: 

Rr9 e (X): 1808 



Locals: 



Mot* abovt 



(DO-RRROU) 

(0RRU-RRR0U-6RRPHIC 1288 1888 1888) 
(0RRU-8IG-RRR0U) 
(STRIPE-RRROWHERD) 
(COMPUTE-MLINES 1888) 
■►(CONPUTE-DENS 1888) 



Moz* btlow 



Return to nornal debugger, staying In error conteKt. 

Supply replacencnt argunent 

Return a value fron the — INTERNRL Instruction 

Retry the — INTERNRL Instruction 

Lisp Top Level in Lisp Listener 1 



What Error 
Rrglist 



Inspect 
Edit 



Retry 



MIL 



Return 
Throw 



Set arg 
Search 



>>Trap: The first argunent given to SYS: — INTERNAL, NIL, was not a nunber. 



Choose a value by 
88/28/83 17:82:85 



jets object Into error handler. 
i: Tyl 



pointing at the value, 
ron 



Right ' 
GRflPHICI 



Figure 7. The Display Debugger: inspecting the variable •x2*. 
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(defun do-arrows () 

;: Don't exceed maximum recursion level 
(when (< 'depth* •max-depth*) 

;; Bind values for half and one-fourth of top edge 
(let ((•top-edge-2» (// »top-edge» 2)) 
(»top-edge-4« (// »top-edge* 4))) 
(draw-arrow) ;Draw a small arrow 

;; Increment depth. Divide top edge 1n half. Bind new 
;; coordinates for top right point of next arrow, 
(let (('depth* (1+ »depth*)) 

(*top-edge* •top-edge-2*) 
(*pOx* (+ »top-edge-4* (- 'pOx* «top-edge*))) 
(*pOy* (- *pOy* 'top-edge-a*))) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; Increment depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow, 
(let (('depth* (1+ *depth*)) 

(•top-edge* *top-edge-2*) 
(*pOx* (- *pOx* *top-edge-2«)) 
(*pOy* (+ *top-edge-4* (- *pOy* *top-edge*)))) 
;: Draw a right-hand child arrow 
(do-arrows))))) 

This code produces the result shown in flgure 8 (page 81). Something is 
clearly wrong with at least one of the function calls, but the complexity of 
the Hgure makes it difficult to see the source of the error. We simplify the 
Hgure by making a comment of the second recursive function call: 
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(defun do-arrows () 

;; Don't exceed maximum recursion level 
(when (< 'depth* 'max-depth*) 

;; Bind values for half and one-fourth of top edge 
(let (Ctop-edge-Z* (// nop-edge* 2)) 
(•top-edge-4» (// 'top-edge* 4))) 
(draw-arrow) ;Draw a small arrow 

;; Increment depth. Divide top edge In half. Bind new 
; ; coordinates for top right point of next arrow, 
(let (('depth* (1+ "depth*)) 

(*top-edge* *top-edge-2*) 

(•pOx* (+ *top-edge-4* (- «pOx* 'top-edge*))) 
(*pOy' (- 'pOy' 'top-edge-Z'))) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; Increment depth. Divide top edge In half. Bind new 
;; coordinates for top right point of next arrow. 
#1 

(let (('depth* (1+ 'depth')) 

(*top-edge* *top-edge-2*) 
(*pOx* (- *pOx* *top-edge-2*)) 
(*pOy* (+ «top-edge-4* (- *pOy* *top-edge*)))) 
:; Draw a right-hand child arrow 
(do-arrows))))) 
l# 
))) 



We recompile do-arrows (using c-sh-C), run the program again, and obtain 
the results shown in figure 9 (page 82). The small arrows now apjpear to be 
the right size, and the number of recursion levels is correct. The problem 
seems to lie in the positioning of the arrows, or the calculation of the new 
values for *pOx* and •pOy*. On close inspection, we see that the x- 
coordinates look correct, but the y-coordinates are wrong. Instead of 
obtaining the new value of 'pOy* by subtracting ♦top-edge-2* from the old 
*pOy*, we should subtract *top-edge-4* from 'pOy*. We change the 
definition of do-arrows: 
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(defun do-arrows () 



(let ((*depth« (1+ ^depth*)) 

(*top-edge» »top-edge-2*) 

(*pOx» (+ »top-edge-4» (- »pOx* «top-edge«))) 
(«pOy* (- »pOy« *top-edge-4«))) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; Increment depth. Divide top edge in half. Bind new 
;; coordinates for top right point of next arrow. 



#1 



(let (('depth* (1+ 'depth*)) 

(•top-edge* *top-edge-2*) 

(•pOx* (- *pOx* *top-edge-2«)) 

(*pOy* (+ •top-edge-4* (- »pOy* "top-edge*)))) 
;; Draw a right-hand child arrow 
(do-arrows))))) 



») 



When we recompile do-arrows and run the program again, we obtain the 
results shown in figure 10 (page 83). The first recursive function call is 
now correct. Looking at the arguments in the second function call, we see 
that the same error ejusts in the calculation of the new ♦pOx*: We should 
subtract ♦top-edge-4*, not *top-edge-2«, from the old •pOx*. We make 
the change, remove the #| and |#, and recompile do-arrows. We obtain 
the results shown in figure 1 (page 18). 

Example 

Figure 4 (page 59) shows a split screen, with graphic output in the upper 
window and source code in the lower. To adjust the size of the graphic for 
the smaller window, we have to change the arguments to 
draw-arrow-graphic when we call that function from do-arrow. We want 
to keep a record of the arguments we use to produce a full-screen figure. 
We can make a comment of the call to draw-arrow-graphic that uses full- 
screen arguments: 

(defun do-arrow () 

(setq *dest* (make-instance 'screen-arrow-output)) 

(send terminal-io • :clear-screen) 
; (draw-arrow-graphic 1280 1800 1800)) 

(draw-arrow-graphic 640 1300 1800)) 
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Figure 8. Output resulting from a faulty attempt to outline the small arrows recursively. 
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NIL 




Lisp Listener 1 



88/16/83 19:02:25 ron 



GRHP 



ICS^y^T 



Figure 9. Output resulting from a faulty attempt to outline the small arrows recursively, with 
the second function call commented out. 
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Figure 10. Output resulting from a corrected attempt to outline the small arrows recursively, 
with the second function call commented out. 
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4.4 Tracing and Stepping 



4.4.1 Tracing 



When a program runs but behaves unexpectedly, you might be calling 
functions in the wrong sequence or passing incorrect arguments. Tracing 
function calls can help detect this sort of problem. By default, tracing 
prints a message, indented according to the level of recursion, on entering 
and leaving a function. It also prints the arguments passed and the values 
returned. 

You can invoke tracing in three ways: 

• Click on [Trace] in the system menu 

• Use Trace (tn-X) in Zmacs 

• Use the trace special form 

[Trace] and Trace (m-X) pop up a menu of options, including stepping and 
inserting breakpoints. You can use these options with trace, too, but the 
syntax is complex. Table 1 (page 87) summarizes the correspondence 
between trace menu items and trace options. See the Lisp Machine Manual, 
section 26.3, page 457, for a description of the options. 

Example 

Suppose that we had begun writing the recursive function calls in do-arrows 
with the following code, passing arguments to do-arrows instead of binding 
the special variables: 

(defun draw-arrow-graphic (»top-edge» 'pOx* 'pOy*) 



(draw-big-arrow) 

(do-arrows *top-edge-2» (- •pOx» «top-edge-Z*) (- «pOy« *top-edg8-2«))) 
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(defun do-arrows (»depth* *top-edge« 'pOx* *pOy*) 
;: Don't exceed maxlfflum recursion level 
(when (< 'depth* «inax-depth*) 

;; Bind new values for half and one-fourth of top edge 
(let ((»top-edge-2* (// nop-edge* 2)) 
(•top-edge-4» (// nop-edge* 4))) 
;; Draw a small arrow 
(draw-arrow) 

;; Draw a left-hand child arrow, dividing top edge In half, 
incrementing depth, and passing new coordinates for top 
right point 
(do-arrows *top-edge-2« (1+ «depth*) 

(+ »top-Gdge-4* (- »pOx« «top-edge*)) 
(- 'pOy* •tDp-edge-4*)) 
;; Draw a right-hand child arrow, dividing top edge in half, 
:; incrementing depth, and passing new coordinates for top 

right point 

(do-arrows 'top-edge-Z* (1+ «depth*) (- 'pOx* »top-edge-4*) 
(+ »top-edge-4» (- 'pOy* «top-edge*)))))) 

This code produces only the first of the small arrows. Again, something 
appears to be wrong with the recursive function calls. Using Trace (m-X), 
we trace calls to do-arrows. We run the program again, and the following 
trace output appears: 

(1 ENTER DO-ARROWS (0 640 1160 1160}) 

(2 ENTER 00-ARROWS (320 1 680 1000)) 

(2 EXIT DO-ARROWS NIL) 

(2 ENTER DO-ARROWS (320 1 1000 680)) 

(2 EXIT DO-ARROWS NIL) 
(1 EXIT DO-ARROWS NIL) 
NIL 



The problem here is immediately apparent: The order of the first two 
arguments in the recursive function calls is reversed. We are passing the 
new value of 'top-edge* as the new value of •depth*. Because this value 
exceeds that of *max-depth*, the function returns after the first recursive 
call. 

Reference 

Trace (m-X) Traces or untraces a specified 

function. Prompts for the name of a 
function to trace and pops up a menu 
of trace options. 

[Trace] (from a system menu) Traces or untraces a specified 

function. Prompts for the name of a 



function to trace and pops up a menu 
of trace options. 
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(trace (function function-spec- 1 option- 1 option-2 ^ J) 

Enables tracing of one or more 
functions. If function-spec is a 
symbol, the keyword cfunction is 
unnecessary. An argument can also 
be a list whose car is a list of 
function names and whose cdr is one 
or more options. In this case, all 
functions in the list are traced with 
the same options. With no 
arguments, returns a list of functions 
being traced. 

(untrace f;fmiction function-spec- T) ^ 

Disables tracing of one or more 
functions. If function-spec is a 
symbol, the keyword :fQnction is 
unnecessary. With no arguments, 
untraces all functions being traced. 



4.4.2 Stepping 



When a program behaves unexpectedly and tracing doesn't reveal the 
problem, you might step through the evaluation of a function call. You can 
step through function execution by using step, [Step] from a trace menu, or 
the :step option to trace. 

You can step through the execution of a function only if it is interpreted, 
not compiled. If you want to step through execution of a compiled 
function, read the definition into a Zmacs buffer and use a Zmacs command 
(such as c-sh-E) to evaluate it (see section 3.2.1, page 66). 

The Stepper prints a partial representation of each form evaluated and the 
values returned. A back arrow («■) precedes the representation of each form 
being evaluated. A double arrow (») precedes macro forms. A forward 
arrow (■►) precedes returned values. 

After printing, the Stepper waits for a command before proceeding to the 
next step. Stepper commands allow you to specify the level of evaluation to 
be stepped, escape to the editor, or enter a Lisp breakpoint loop. Press 
HELP inside the Stepper or see the Lisp Machine Manual, section 26.5, 
page 464, for a list of commands. Following are some basic Stepper 
commands: 

Command Action 

c-N Evaluate until next thing to print 

SPACE Evaluate until next thing to print at this level (don't step 

at lower levels) 
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Table 1. Trace Menu Items and trace Options 
Trace menu item trace option 

[Cond break before] :break predicate 



[Break before] 


:break t 


[Cond break after] 


:exitbreak predicate 


[Break after] 


rexitbreak t 


[Error] 


:error 


[Step] 


:step 


[Cond before] 


:entrycond predicate 


[Cond after] 


:exitcond predicate 


[Conditional] 


:cond predicate 


[Print before] 


:entryprint form 


[Print after] 


:exitprint form 


[Print] 


rprint form 


[ARGPDL] 


.-argpdl pdl 


[Wherein] 


:whereln function 


[Untrace] 





:entry list 

:exit list 

:arg rvalue :both :nil 



Description 

Enters breakpoint on function entry 
if predicate not nil 

Enters breakpoint on function entry 

Enters breakpoint on function exit 
if predicate not nil 

Enters breakpoint on function exit 

Enters Debugger on function entry 

Steps through (interpreted) function 
execution (see section 4.4.2, page 86) 

Prints trace output on function 
entry if predicate not nil 

Prints trace output on function 
exit if predicate not nil 

Prints trace output on function 
entry and exit if predicate not nil 

Prints value of form 
in trace entry output 

Prints value of form 
in trace exit output 

Prints value of form in 
trace entry and exit output 

On function entry, pushes list 
of function name and args onto 
pdl; pops list on function exit 

Traces function only when 
called within function 

Calls ontrace on function 

Prints values of forms in 
list on function entry 

Prints values of forms in 
list on function exit 

Controls printing of args 
on function entry and values 
on function exit 
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c-U Evaluate until next thing to print at next level up (don't 

step at current and lov?er levels) 

c-B Enter breakpoint loop 

c-E Enter Zmacs 

c-X Evaluate until finished (exit from stepping) 



Example 

We have the same problem with the function do-arrows as we described in 
section 4.4.1 (page 84). The program outlines only the largest of the small 
arrows, indicating a problem with the recursive function calls. Instead of 
just tracing do-arrows, we step through its evaluation. We first use c-sh-E 
to evaluate the definition of do-arrows. We then use [Step] in the menu 
that Trace (m-X) pops up to trace and step through do-arrows. We run 
the program. The Stepper waits for a command before evaluating each 
form in do-arrows. We press SPACE to skip to the next form at the same 
level. When we come to the comparison of *depth* and ♦max-depth* in 
the recursive calls, we want to see each level of evaluation. We press c-N 
at each of these steps. The tracing and stepping output looks as follows: 

(1 ENTER DO-ARROWS (0 640 1160 1160)) 

• (WHEN (< "DEPTH* 'MAX-DEPTH*) (LET (('TOP-EDGE-Z* {// »TOP-EDGE* 
*■ (COND ((< «DEPTH* 'MAX-DEPTH*) (PROGN (LET (("TOP-EDGE-Z* (// 'T 

(2 ENTER DO-ARROWS (320 I 680 1000)) 

• (WHEN (< 'DEPTH* *MAX-DEPTH«) (LET ((*T0P-EDGE-2* (// »TOP-EDGE« 
*■ (COND ((< 'DEPTH* "MAX-DEPTH*) (PROGN (LET ( (*T0P-EDGE-2* (// *T 

*■ (< *DEPTH* *KAX-DEPTH*) 

«- *DEPTH* ■♦ 320 

«- *MAX-DEPTH« -» 7 
<- (< 'DEPTH' 'MAX-DEPTH') -» NIL 
*■ (COND (« 'DEPTH* 'MAX-DEPTH') (PROGN (LET (('TOP-EDGE-2' (// "T •♦ NIL 
(2 EXIT DO-ARROWS NIL) 
(2 ENTER DO-ARROWS (320 1 1000 680)) 

• (WHEN (< 'DEPTH' 'MAX-DEPTH*) (LET ((*T0P-EDGE-2« (// 'TOP-EDGE' 
«• (COND ((< 'DEPTH' 'MAX-DEPTH') (PROGN (LET ((*T0P-EDGE-2* (// 'T 

*■ (< 'DEPTH* 'MAX-DEPTH*) 
♦■ *OEPTH* -► 320 
«- *MAX-DEPTH' •♦7 
*■ « 'DEPTH' 'MAX-DEPTH') -» NIL 
*■ (COND ((< 'DEPTH' 'MAX-DEPTH*) (PROGN (LET (('TOP-EDGE-2' (// 'T -» NIL 

(2 EXIT DO-ARROWS NIL) 
(1 EXIT DO-ARROWS NIL) 
NIL 

In this example, stepping shows even more clearly than tracing that the 
value of *depth* is wrong in the recursive function calls. 
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Reference 

(step form) Steps through the evaluation of form 

Trace (m-X) [Step] Steps through the execution of a 

function being traced. 

[Trace / Step] (from a system menu) Steps through the execution of a 

function being traced. 

(trace (:fanction function-spa: :step)) 

Steps through the execution of a 
function being traced. If 
function-spec is a symbol, the keyword 
:functioii is unnecessary. 

4.5 Breakpoints 

In debugging a program, you might want to interrupt function execution to enter a Lisp 
breakpoint loop or the Debugger. Entering the Debugger is usually more useful, for there you 
can examine the stack, return values, and take other steps in addition to evaluating forms. 

You can use two general kinds of breakpoints: 

• You can edit into a definition a call to dbg (with no arguments) or to 
break. The advantage of this kind of breakpoint is that, as with stepping, 
you can interrupt execution within the function. The disadvantage is that 
you have to edit and recompile the definition to insert and remove the 
breakpoint. If you redefine the function after inserting the breakpoint, the 
breakpoint might be lost. 

• You can use breakon or one of the error or break options to trace. These 
features create enccpsulations, functions that contain the basic definitions of 
the functions to which you want to add breakpoints (see the Lisp Machine 
Manual, section 10.10, page 153, for more on encapsulations). The 
advantage of this kind of breakpoint is that when you recompile or 
otherwise redefine the function, only the basic definition is replaced, and the 
breakpoints remain. The disadvantage is that you can interrupt function 
execution only on entry or exit, not within the function. 

You insert these breakpoints by calling breakon or trace from a Lisp 
Listener or by using the trace menu; you remove them by calling 
unbreakon or nntrace. When you break on entering function execution, 
just before applying the function to its arguments, the variable arglist is 
bound to a list of the arguments. When you break on exiting from function 
execution, just before the function returns, the variable values is bound to a 
list of the returned values. 

From either a breakpoint loop or the Debugger, RESUME allows the program to continue, and 
ABORT returns control to the previous break or, if none exists, to top level. 
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Example 

We decide to break on entry to do-arrows and enter the Debugger while 
tracing the function. We use Trace (m-X) and then [Error] from the trace 
menu. We select a Lisp Listener and run the program. On the first entry 
to do-arrows we enter the Debugger, with the following message: 

» TRACE Break: DO-ARROWS entered. 

00-ARROWS: (encapsulated for TRACE) 

Rest arg (ARGLIST): (0 640 1160 1160) 
s-fl, RESUME: Proceed without any special action 
s-B, RBORT: Lisp Top Level In Lisp Listener 1 



Reference 
(dbg process) 



Enters the Debugger in process. With 
an argument of t, finds a process that 
has sent an error notification. With 
no argument, enters the Debugger as 
if an error had occurred in the 
current process. 



(break tas: conditional- form) 



Enters a Lisp breakpoint loop 
(identified as "breakpoint tag") if 
conditional- form is not nil or is not 
supplied. 

(breakon function-spec conditional- form) 

Passes control to the Debugger on 
entering function-spec if 
conditional-form is not nil or is not 
supplied. With no arguments, returns 
a list of functions with breakpoints 
specified by breakon. 

(unbreakon function-spec conditional- form) 

Turns off the breakpoint condition 
specified by conditional- form for 
function-spec. If conditional-form is 
not supplied, turns off all breakpoints 
specified by breakon for 
function-spec. With no arguments, 
turns off all breakpoints specified by 
breakon for all functions. 



[Error] (from a trace menu) 



Passes control to the Debugger on 
entering a function being traced. 
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[Cond break before] (from a trace menu) 

Prompts for a predicate. Displays 
trace entry information and enters a 
Lisp breakpoint loop on entering a 
function being traced if the predicate 
is not nil. 

[Cond break after] (from a trace menu) 

Prompts for a predicate. E>isplays 
trace exit information and enters a 
Lisp breakpoint loop on exiting from 
a function being traced if the 
predicate is not nlL 

(trace (ifunction function-spec :error)) 

Passes control to the Debugger on 
entering a function being traced. If 
function-spa: is a symbol, the keyword 
:function is unnecessary. 

(trace (:fanction function-spec :fcreak predicate^ 

Prints trace entry information and, if 
the value of predicate is not nil, 
enters a Lisp break loop on entering 
the function. If function-spec is a 
symbol, the keyword :fanction is 
unnecessary. 

(trace (:function function-spec :exitbreak predicate)) 

Prints trace exit information and, if 
the value of predicate is not nil, 
enters a Lisp break loop on exiting 
from the function. If function-spec is 
a symbol, the keyword :fanction is 
unnecessary. 

4.6 Expanding Macros 

Sometimes a program bug appears to stem from unexpected behavior by a macro. Seeing how 
a macro form expands can help find the bug. To be sure that a macro does what you want it 
to, you might also want to create and expand a macro form soon after defining the macro and 
compiling the definition. 

You can expand a macro form in a Zmacs buffer using Macro Expand Expression (c-sh-H). 
This command expands the form following point, but not any macro forms within it. To 
expand all subforms, use Macro Expand Expression All (m-X). You can also expand macro 
forms with tnexp, which enters a loop to read and expand one form after another. 

Example 

We have just written code to stripe the shafts of the small arrows, drawing 
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stripes with uniform spacing and density. We produce the results shown in 
figure 1 1 (page 93). We evidently have a problem with the function 
draw-arrow-shaft-stripcs. The code for this function is as follows: 

(defun draw-arrow-shaft-str1pes 

(left-x top-y right-x bottom-y) 
;; Find y-coord of starting point of stripe. Don't go 
;; below the bottom of the triangle. 

(loop for start-y from top-y by 'stripe-distance* above bottom-y 
;; Find x-coord of ending point of the stripe 
for end-x from right-x by •stripe-distance* 
; ; Draw a stripe 
do (draw-arrow-shaft-lines 

left-x start-y end-x bottom-y))) 

The bug stems from incorrect coordinates for the endpoints of the shaft 
stripes. The beginning coordinates (left-x and start-y) are correct. The 
ending y-coordinate (bottom-y) looks right, but the ending x-coordinate 
(end-x) is wrong. The problem might not be evident from looking at the 
code, which consists entirely of a loop form. We move to the beginning of 
the loop form and expand it, using c-sh-M: 

((LAMBDA (START-Y G1049 G1050) 
((LAMBDA (END-X G1051) 
(PROG NIL 

(AND (NOT (GREATERP START-Y G1050)) (GO SI:EKD-LOOP)) 
SI: NEXT- LOOP 

(DRAW-ARROW-SHAFT-LINES LEFT-X START-Y END-X BOTTOM-Y) 
(SETQ START-Y (DIFFERENCE START-Y G1049)) 
(AND (NOT (GREATERP START-Y G1050)) (GO SI:EN0-LOOP)) 
(SETQ END-X (PLUS END-X G105I)) 
(GO SI: NEXT-LOOP) 
SI:END-LOOP 
)) 
RIGHT-X 

•STRIPE-DISTANCE*)) 
TOP-Y 

•STRIPE-DISTANCE^ 
BOTTOM-Y) 

The expansion shows the lambda-bindings and prog form that the loop 
macro creates. We can see that the error is in the setting of end-x within 
the prog form: We are incrementing end-x by ♦stripe-distance*, when we 
should be decrementing it. The problem is in our use of a loop keyword. 
Instead of writing 

for end-x from right-x by *stripe-d1stance^ 
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Figure 11. Output from the program with a bug in the function 
draw-arrow-shaft-stripes. 
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we should have written 



for end-x downfrom rlght-x by •stripe-distance* 



We make the change and recompile draw-arrow-shaft-stripes. 
expand the loop form, we see that we are decrementing end-x: 



Now if we 



((LAMBDA (START-Y G1062 G10S3) 
((LAMBDA (END-X G1064) 
(PROG NIL 

(AND (NOT (GREATERP START-Y G1063)) (GO SI:END-LOOP)) 
SI:NEXT-LOOP 

(DRAW-ARROW-SHAFT-LINES LEFT-X START-Y END-X BOTTOM-Y) 
(SETO START-Y (DIFFERENCE START-Y G1062)) 
(AND (NOT (GREATERP START-Y G1063)} (GO SI:END-LOOP}) 
(SETQ END-X (DIFFERENCE END-X G1064)) 
(GO SI: NEXT- LOOP) 
SI: END-LOOP 
)) 
RIGHT-X 

•STRIPE-DISTANCE*)) 
TOP-Y 

•STRIPE-DISTANCE* 
BOTTOM-Y) 



Reference 

Macro Expand Expression (c-sh-M) 



Macro Expand Expression All (i»-X) 



(mexp) 



Expands the macro form following 
point. Does not expand subforms 
within the form. 

Expands the macro form following 
point and all subforms within the 
form. 

Enters a loop: prompts for a macro 
form to expand, expands it, and 
prompts for another macro form. 
Exits from the loop on nil. 



4.7 The Inspector 

The Inspector is a window-based tool that combines the describe and disassemble functions. 
Invoke it with inspect, SELECT I, or [Inspect] from a system menu. If you use inspect, the 
Inspector is not a separate activity from the Lisp Listener in which you invoke it. In that case 
you cannot use SELECT L to return to the Lisp Listener; you must click on [Exit] or [Return] 
in the Inspector menu. 

The Inspector displays information about an object and lets you modify the object. It displays 
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information for the last object inspected in the bottom window. It displays information for the 
two previous objects in the windows above the bottom one. It maintains a mouse-sensitive 
listing of all inspected objects in the history window. These are some of its useful features: 

• The information the Inspector displays depends on the object's type. For a 
symbol, it displays a representation of the value, function, property list, and 
package. For a symbol's flavor property, it displays information about 
instance variables, component and dependent flavors, the message handler, 
init keywords, and the flavor property list. For a compiled function, it 
displays the disassembled assembly-language code that represents the 
compiler output. 

• The Inspector is especially useful for examining data structures. It displays 
the names and values of the slots of structures and, unlike describe, the 
elements of (one-dimensional) arrays. For instances of flavors, the Inspector 
displays the names and values of instance variables. 

• Within each display, most representations of objects are mouse sensitive. If 
you click on an object representation, you inspect that object. For example, 
you can inspect elements of lists. If an element of an array is itself an 
array, you can inspect the second array. In this way you can follow long 
paths in data structures. 

• You can change a value by using the [Modify] option in the Inspector's 
menu. You can return a value when you exit the Inspector by clicking on 
[Return]. 

See Operating the Lisp Machine, chapter 5, page 28, for more on the Inspector. 



Example 

Suppose we had represented each arrow as an instance of a structure 
(defined with def struct) instead of a collection of special-variable values. 
We could have called the structure representing the small arrows arrow and 
set the value of a special variable, •arr*, to each instance of the structure as 
we created it. 

Figure 12 (page 96) shows an Inspector window for the last arrow in the 
figure. We first run the program in a Lisp Listener, then invoke the 
Inspector using SELECT I. Because we typed (pkg-goto 'graphics) in the 
Lisp Listener, the Inspector's package is graphics. We type *arr» to the 
interaction pane at the top of the frame. The window at the bottom of the 
frame displays the names and values of the structure slots. We can change 
these values by using the [Modify] menu option. 

Example 

Suppose we had represented each arrow as an instance of a flavor and 
defined most of our computation functions as flavor methods instead of 
simple functions. We could have called the flavor representing the small 
arrows arrow and set the value of *arr* to each instance of the flavor as 
we created it. 
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Figure 12. The Inspector window: inspecting an instance of a structure. 
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Figure 13 (page 98) shows an Inspector window for the last arrow in the 
figure. As with our structure example, we first run the program and then 
invoke the Inspector to evaluate 'arr* and inspect the flavor instance that is 
its value. The Inspector displays the names and values of instance variables 
and a representation of the flavor's message handler. 

We next click on the mouse-sensitive representation of the message handler. 
The Inspector displays a representation of the function spec for the method 
that handles each message. If we click on the function spec for the 
:compute-dens method for flavor basic-arrow, the Inspector displays the 
method's disassembled code. 



Reference 
(inspect object) 

SELECT I 

[Inspect] (from a system menu) 

(disassemble function) 

Disassemble (m-X) 



Selects an Inspector window in which 
to inspect object. 

Selects an Inspector window. 

Selects an Inspector window. 

Prints a representation of the 
assembly-language instructions for a 
compiled function. 

Prompts for the name of a compiled 
function and displays a representation 
of the function's assembly-language 
instructions. 
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Figure 13. The Inspector window: inspecting an instance of a flavor. 
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5. Using Flavors and Windows 

All Lisp Machine Lisp programmers must know how to use flavors and the window system in 
at least an elementary way. Flavors are the basis of a powerful, nonhierarchical kind of object- 
oriented programming. Even if you don't use them extensively, the system code does. 
Applications that include screen display or user interaction must deal with the window system, 
which is itself built on flavors. 

In this chapter we present a brief introduction to using flavors and windows. We do not 
discuss the concepts and organization of flavors and the window system in any detail. Instead, 
we modify the output module of our example program to show some simple uses of flavors, 
windows, and menus. We show basic examples of the following features: 

• Using base, mixin, and instantiate flavors and :daemon method 
combination 

• Creating a simple window and associating it with a process 

• Producing LGP output 

• Altering values using a choose-variable-values window 

• Signalling a condition and proceeding 

We also present some editor commands and Lisp functions for finding information about 
flavors and windows. Among the issues we do not discuss in any detail are the following: 

• Using types of method combination other than :daemon 

• Interacting with the mouse process 

• Creating frames 

• Specifying fonts 

• Using menus 

For more information on flavors and windows, read the following documents: 

• On flavors: Lisp Machine Manual, chapter 20, page 279 

• On windows: Introduction to Using the Window System 

• On menus: Lisp Machine Choice Facilities 

• On conditions and errors: Signalling and Handling Conditions 

5.1 Program Development: Modifying the Output Module 

As now written, the output routines of our example program consist of a flavor and methods 
that produce lines on the stream to which terminal-io is bound: 

(defflavor screen-arrow-output 
((scale-factor 2.5)) 
()) 
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(defnethod (screen-arrow-output :show-11nes) 
(X y &rest x-y-pairs) 
(loop for xO = (send self 'icomputo-x x) then xl 
for yO = (send self ':compute-y y) then yl 
for (xl yl) on x-y-paIrs by #'cddr 
do (setq xl (send self *:compute-x xl) 

yl (send self ' :compute-y yl)) 
(send terminal-1o ':draw-l1ne 

xO yO xl yl tv:alu-ior t))) 

(defnethod (screen-arrow-output :compute-x) (x) 
(fixr (// X scale-factor))) 

(defmethod (screen-arrow-output :compute-y) (y) 
(fixr (- 800 (// y scale-factor)))) 

We want to be able to produce output on the screen, an LGP, or a file. For this we need a 
simple device-independent graphics system that uses generic operations. The central operation is 
:show-lines, which receives endpoint coordinates from the calculation module and produces 
lines on the appropriate output stream. Our general strategy for creating the output options is 
as follows: 

1. Define a flavor and methods to calculate the position of the arrow figure on 
the screen or page. We can use this mixin with flavors that produce any 
kind of output. 

2. Define flavors and methods to produce screen output. We build the 
instantiable flavors on tv.window and instantiate them with 
tv:make-window. We define two kinds of arrow window flavors: 

• A basic flavor that performs output and redisplays the window after 
changes. 

• A flavor, which we instantiate, that is built on the basic window and 
includes a mixin to convert LGP coordinates to screen coordinates. 

3. Define a flavor and methods to produce LGP or file output. 

4. Define a top-level function that uses a choose-variable-values window to 
select the type of output and alter some variables. The function calls 
tv:make-window or makes an instance of the LGP flavor, depending on the 
output type. 

5. Change the arrow-window flavors to allow multiple windows, associate each 
window with its own process, and allow the user to modify the 
characteristics of the figure in each window. 

6. Define a function to check for mistakes when the user changes the values 
of variables. We define condition flavors for the incorrect choices. We 
define handlers for the conditions and use signal to signal them. We allow 
the user to proceed by supplying new values for the variables. 
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We want to preserve modularity in writing these new routines. We define the flavor that 
positions the arrow figure so that we can use it with any sort of output. We keep the 
operations that transform LGP to screen coordinates separate from the basic window 
operations. We define the routines that handle bad variable values as separate flavors and 
functions. These precautions make it easy to define new kinds of windows or to check for 
errors in other variable values in the future. 

5.1.1 A Mixin to Position the Figure 

No matter what the output device, we want to be sure that the figure fits 
within the bounds of the page or window and is centered within the page or 
window. We define a mixin flavor, arrow-paraiaeter-mixin, with methods 
to perform these calculations. We include this flavor in all flavors that 
produce output for the figure. 

We define five instance variables to hold the parameters. Three of these, 
top-edge, right-x, and top-y, are the arguments we must pass to the 
calculation module. We make these three instance variables gettable so that 
we can retrieve them by sending messages to an instance of the dependent 
flavor. The other two instance variables are the width and height of the 
page or window in the appropriate units, either LGP or screen pixels. 

(defflavor arrow-parameter-mlxln 

(width height top-edge right-x top-y) 

() 

( :gettab1e-instance-var1ab1es top-edge right-x top-y) 

(: documentation :mixin 
"Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; coordinates of top right point 
of figure.")) 

The task of this flavor is to perform a generic operation, which we call 
tcompute-parameters. This operation consists of separate computations for 
top-edge, right-x, and top-y. We define primary methods for these 
operations here, using coordinates with the origin at bottom left. Flavors 
that mix in this one can add daemons, whoppers, or their own primary 
methods to accommodate other coordinate systems and scale factors. 

We perform these operations as follows: 

1. Determine the width and height of the page or window. The details of this 
operation are the business of other flavors. We specify a required method, 
:compate-width-and-helght, for any flavor that mixes in this one. We send 
self a :compute-width-and-height message to set the instance variables. 

2. Calculate a provisional value for top-edge so that the figure fits within the 
smaller dimension of the page or window. We allow the user to specify, by 
setting the global variable •fill-proportion*, what fraction of this dimension 
the figure should fill. 
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3. Adjust the top edge so that its value is at least 128 and is a multiple of 128 
if larger. This adjustment ensures that stripe spacing is continuous 
throughout the levels of the figure. 

4. Calculate right-x and top-y so that we center the figure within the page or 
window. 

The complete code for this flavor and its methods is as follows: 

(defvar •fm-proport1on» 0.9 
"Proportion of smaller dimension to be filled by figure") 



(defflavor arrow-parameter-mixin 

(width height top-edge right-x top-y) 

() 
(rgettable-instance-variables top-edge right-x top-y) 

( :required-methods :compute-width-and-height) 

( idocumentation :mixin 
"Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; coordinates of top right point 
of figure. Methods calculate size and position of figure by 
centering it within the page or window and making it fill no 
more than the specified proportion of the smaller dimension. 
The methods use a coordinate system with origin at bottom left; 
other mixins must correct for this if output is going to a 
window. Other flavors must also provide a method for calculating 
width and height of the page or window. This flavor should be 
mixed into any instantiable flavor that produces output for the 
arrow graphic.")) 

;;; Hethod controlling calculation of size and position of figure. 
;:: Sends messages to self to calculate width and height of page 
;;; or window, length of top edge of figure, and coordinates of 
;;; figure's top right point. These are separate methods so that 
;;; other flavors can shadow them or add daemons. Another flavor 
;;; must provide a method to compute width and height, because 
;;; this Is specific to the output device, 
(defmethod (arrow-parameter-mixin :compute-parameters) () 

;; Another flavor roust supply method for width and height 

(send self ':compute-width-and-he1ght) 

;; Make a preliminary estimate of length of top edge 

(send self ' :compute-top-edge) 

;; Adjust top edge to make it a multiple of 128 

(send self ' :adjust-top-edge) 

;; Calculate coordinates of top right point of figure. 

;; We can't do this until we know how long top edge Is. 

(send self ' :compute-right-x) 

(send self ':compute-top-y)) 
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Makes a preliminary estimate of length of top edge. 
The top edge of the arrow Is 80 percent of the horizontal 
or vertical length of the whole figure. First finds the 
smaller of the length or width of the page or window. 
Hultlplies this by the proportion of this dimension that 
is to be filled by the figure. The result is the 
horizontal or vertical length of the figure. Multiplies 
this by 0.8 to get the length of the top edge, 
(defmethod (arrow-parameter-mlxin :compute-top-edge) () 
(setq top-edge 

(fixr (• 0.8 «fni-proport1on« (min width height))))) 

Adjusts length of top edge so it Is a multiple of 128. 
There are 64 stripes in the head of the large arrow. The 
calculation module divides the length of top edge by two 
each time it goes down another recursion level. By making 
the original top edge a multiple of 128, we maximize 
continuity In striping between arrowheads and shafts and 
among the first several levels of recursion, 
(defmethod (arrow-parameter-m1x1n :adjust-top-edge) () 
(setq top-edge 

;; Minimum length of top edge Is 128 
(If (< top-edge 256) 128 

;; Otherwise set to next lower multiple of 128 
(• 128 (fix (// top-edge 128)))))) 



Calculates x-coordinate of top right point of figure. 
Finds horizontal length of figure by dividing length of 
top edge by 0.8. Centers the figure horizontally within 
the page or window, 
(defmethod (arrow-parameter-nixin :compute-r1ght-x) () 
(setq rlght-x 

(fixr (• 0.5 (+ width (// top-edge 0.8)))))) 

Calculates y-coordlnate of top right point of figure. 
Assumes that the origin Is at bottom. Finds vertical 
length of figure by dividing length of top edge by 0.8. 
Centers the figure vertically within the page or window, 
(defmethod (arrow-paraneter-ralxin :compute-top-y) () 
(setq top-y 

(fixr (• 0.5 (+ height (// top-edge 0.8)))))) 



5.1.2 The Basic Arrow Window 

We want to buUd our window on tv:window, a flavor that produces a 
simple window with borders, a label, and graphics. Any arrow window we 
use must provide for initialization and redisplay, determine its width and 
height, and supply a :show-lines method to draw our figure. 

We define a mixin flavor, basic-arrow-window-mixin, with methods to do 
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these things. We require that this flavor be used with 
arrow-paranjeter-mixin and tv:window. For the basic window, we assume 
that the coordinates supplied to :show-lines are screen coordinates, with 
origin at top left. 

We write basic-arrow-window-mixin as follows: 

1. Define the flavor. The irequired-flavors option ensures that we have 
access to the flavors' instance variables and that an error will be signalled if 
someone makes an instance of a flavor that includes 
basic-arrow-window-mixin but not the required flavors. The 
:default-init-plist option provides values for some elements of the 
initialization property list in case no one else specifies them. The 
:edges-froni option with an argument of ':mouse allows the user to specify 
the initial size and position of the window by using mouse corners. We give 
an initial minimum width and height for the window because the length of 
top-edge must be at least 128, and we want the entire figure to fit inside 
the window. 

(defflavor basic-arrow-window-mixin () () 

(: required-flavors arrow-parameter-rnixin tv:window) 
(:default-1nit-p11st 
:edges-froin ':mouse :minitnurn-width 200 zminimum-height 200 
:b1inker-p nil :expose-p t) 
( rdocumentation :mixin 
"Provides for a basic window to display the arrow graphic. 
ARROW-PARAMETER-MIXIN is needed to position the figure within 
the window. This flavor assumes window coordinates, with origin 
at top left.")) 

2. Provide a :show-lines method to draw lines on the screen. We use 
essentially the same methods as in our original output module, but now we 
assume that the arguments are screen coordinates. We define separate 
:conipate-x and :coinpute-y methods to transform the coordinates so that 
we can shadow these methods when we define another flavor to handle LGP 
coordinates. To produce the lines we use the :draw-line method defined 
for tv:graphics-mixin, a component of tv:window. (In zdaemon method 
combination, when two component flavors have primary methods for the 
same message, the method of the flavor listed earlier in the component 
ordering shadows, or replaces, the method of the flavor listed later. For 
more on method combination, see the Lisp Machine Manual, section 20.12, 
page 306.) 
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;;; Receives endpoint coordinates and draws lines on a window. 
;;; Arguments are alternating x- and y-coordinates of the end- 
;;: points of lines to be drawn. If there are more than two pairs 
;;; of coordinates, assumes that the endpoint of one line Is the 
;;; starting point of the next. Sends messages for separate methods 
;;; to determine the actual coordinates. This Is so that other 
;;; flavors can modify the coordinates. Draws a line by sending self 
;;; a :ORAW-LINE message, and so assumes that TV:GRAPHICS-mXIN is 
;;; Included somewhere to provide this method, 
(defmethod (basic-arrow-window-mixin :show-lines) 
(x y &rest x-y-pairs) 
;; First determine the starting point of the line. On 
;; subsequent trips through the loop, the last endpoint 
;; becomes the next starting point, 
(loop for xO = (send self ':compute-x x) then xl 
for yO = (send self ':coinputa-y y) then yl 
:; "Cddr" down the list created by making all but the 
;; first pair of coordinates an Sirest argument 
for (xl yl) on x-y-pairs by #'cddr 
;; Determine the endpoint of the line 
do (setq xl (send self ':compute-x xl) 
yl (send self ':compute-y yl)) 
;; Draw the line 
(send self ':draw-line 

xO yO xl yl tv:alu-ior t))) 



;;; Determines the x-coordlnate of an endpoint of a line. 
;;: This is a separate method so that other flavors can shadow 
;;; It or add daemons to manipulate the coordinate, 
(defmethod (basic-arrow-window-mixin :compute-x) (x) 
(fixr x)) 



Determines the y-coordinate of an endpoint of a line. 
Assumes that the argument already uses window coordinates, 
with origin at top left. This is a separate method so that 
other flavors can shadow It or add daemons to manipulate 
the coordinate, 
(defmethod (basic-arrow-window-mixin :compute-y) (y) 
(fixr y)) 



3. Supply the rcompnte-width-snd-height method required by 
arrow-parameter-mixin. We use the :inside-size message to 
tv:mInlmum-window, a component of tv:window. We use multiple-value 
to set the instance variables width and height. 
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;;; Finds the inside width and height of the window. 

;;; Sends self an :INSIDE-SIZE message, and so assumes that 

;;; TV:MINIMUM-WIKDOW Is Included somewhere to provide this 

;; ; method. 

(defmethod (baslc-arrow-window-raixin 

:compute-w1dth-and-helQht) () 
(multiple-value (width height) 
(send self ':1ns1de-s1ze))) 

4. Alter the computation of top-y to take account of the screen's origin at top 
left. We can do this in three ways: 

• Define a new primary method for :compnte-top-y to shadow the method we 
defined for arrow-parameter-mixin. We would have to be careful to place 
baslc-arrow-window-mixin before arrow-parameter-mixin in the list of 
component flavors for any flavor we wanted to instantiate. 

• Define :before and rafter daemons for :compute-top-y. The :before 
daemon would make top-edge negative and the :after daemon would make 
it positive again. (In :daeiaon method combination, :before methods for a 
message run before the primary method, and :after methods run after the 
primary method. If two component flavors have daemons for the same 
message, the ibefore method of the flavor listed earlier in the component 
ordering runs before the rbefore method of the flavor listed later, and the 
:after method of the flavor listed earlier runs after the :after method of 
the flavor listed later. For more on method combination, see the Lisp 
Machine Manual, section 20.12, page 306.) 

• Define a whopper for :compute-top-y. This would do the same thing as the 
two daemons, except that when all the :compute-top-y methods were 
combined it would run outside any daemons. (A whopper wraps the 
execution of some code around the execution of a method, running before 
all tbefore daemons and after all :after daemons. For more on whoppers, 
see the System 210 Release Notes, section 7.3, page 41.) 

We define a new primary method in this case because it repeats relatively 
little code and makes the operation of the method clearer. If we used a 
whopper here, someone might mix in another flavor with daemons that 
would unexpectedly run inside our whopper. 

;;; Calculates y-coordinate of top right point of figure. 

:;; Finds vertical length of the figure by dividing the length 

;;; of top edge by 0.8. Centers the figure vertically within 

;;; the window. Gives the result in window coordinates, with 

:;; origin at top left. This method shadows that in 

'; '; ; ARROW-PARAMETER-MIXIN . 

(defmethod (baslc-arrow-window-mixin :cofflpute-top-y) () 

(setq top-y 

(fixr (• 0.5 (- height (// top-edge 0.8)))))) 
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5. Calculate the figure's size and position and redisplay the window at 
appropriate times. We have to recompute the figure's size and position after 
the window is initialized and after its size or margins change. We have to 
redisplay the figure when the window is refreshed, but only if the window 
has no bit-save array or its size has changed. Before redisplaying, we have 
to clear the screen if the window has a bit-save array. 

We perform these tasks by defining :af ter daemons for three messages that 
the system can send to a window: :init, :change-of-size-or-raargins, and 
:refresh. You need daemons like these for most window-system 
applications. 



;;; Calculates size and position of figure after Initialization, 
(defmethod (baslc-arrow-wlndow-mlxln rafter :1n1t) (ignore) 
(send self * :compute-paraineters)) 

;;; Calculates size and position of figure after window change, 
(def method (basic-arrow-window-mixin 

rafter :change-of-size-or-margins) (&rest Ignore) 
(send self ': compute-parameters)) 



;;; Draws the figure when necessary after window Is refreshed, 
(defraethod (basic-arrow-window-mixin rafter rrefresh) 
(&optiona1 type) 
;; Draw figure If not restored from a bit-save array ... 
(when (or (not tvrrestored-bits-p) 

;; ... or size has changed, 
(eq type 'rslze-changed)) 
;; If restored from a bit-save array, clear screen first 
(when tvrrestored-bits-p 

(send self 'rclear-screen)) 
;: Bind 'DEST* to self 
(let (('dest* self)) 
;; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 



We can now define a flavor of window, basic-arrow-window, built on our 
two mixin flavors and on tvrwindow. The order of combination of flavors 
is important. We need to include basic-arrow-window-mixin before 
arrow-parameter-mixin so that the zcompute-top-y method for 
basic-arrow-window-mixin shadows that for arrow-parameter-mixin. We 
must also put basic-arrow-window-mixin before tvrwindow so that our 
:after daemons will run after any that tv:window or its components might 
provide. 
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(def flavor basic-arrow-window () 

(baslc-arrow-window-mlxln 
arrow-par anieter-ml X 1 n 
tv:w1ndow} 
(:documentat1on :combination 
•Instantlable flavor providing a basic window for output. 
Though this flavor is instantlable, its methods assume that 
point coordinates use the window coordinate system, with 
origin at top left. To work with the current calculation 
module it needs another mixin to convert LGP to screen 
coordinates. In the component flavors, BASIC-ARROW-WINDOW-MIXIN 
must come before ARROW-PARAMETER-MIXIM and TV:WINDOW for 
shadowing and daemons to work correctly.")) 



We can actually make an instance of this flavor. We define no new 
methods for it, leaving all methods to component flavors. If we had a 
calculation module that used screen coordinates, basic-arrow-window would 
be the right flavor to use for screen output. 



5.1 .3 Converting LGP to Screen Coordinates 

Because our calculation module uses LGP coordinates, we need another 
flavor of window to produce output. We define a flavor, 
Igp-window-mixin, to be mixed in with basic-arrow-window. We need a 
new instance variable, scale-factor, whose value is the ratio of LGP to 
screen pixel densities. 



(defflavor lgp-w1ndow-m1xin 
((scale-factor 2.5)) 

() 

( :r6qu1red-f lavors basic-arrow-window) 

( :docunentat1on :mixin 
"Converts LGP to screen coordinates and vice versa. 
When mixed in with BASIC-ARROW-WINDOW, this flavor allows 
window output with a calculation module that uses LGP 
coordinates. The Instance variable SCALE-FACTOR is the 
ratio of LGP to screen pixel density. The methods take 
the height and width of the window In screen pixels and 
calculate the length of the top edge and the coordinates 
of the top right point of the figure In LGP pixels. In 
drawing lines on the window, the methods convert LGP to 
window coordinates. These methods shadow those In 
ARROW-PARAMETER-MIXIN and BASIC-ARROW-WINDOW-MIXIN.")) 



We next define new primary methods to incorporate the scale factor into 
the calculation of top-edge, rlght-x, and top-y. These methods shadow 
those defined for arrow-parameter-mixin and basic-arrow-window-mixin. 
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;;; Calculates top edge 1n LGP pixels from screen proportions 
;;; Multiplies length of smaller dimension. In screen pixels, 
;;; proportion of this dimension to be filled by the figure. 
;;; Multiplies this by 0.8 to find top edge in screen pixels. 
;;; Corrects for higher density of LGP pixels. This method 
;;; shadows that of ARROW-PARAMETER-MIXIN. 
(defmethod (Igp-wlndow-mixin :compute-top-edge) () 
(setq top-edge 

(fixr (• scale-factor 0.8 •fill-proportion* 
(min width height)})}} 



by 



;;; Calculates x-coord of top right point in LGP pixels. 
;;; Finds horizontal length of figure In screen pixels by 
;;; dividing top edge by 0.8. Centers figure horizontally 
;;; in window, correcting for higher density of LGP pixels. 
;;; This method shadows that of ARROW-PARAMETER-MIXIN. 
(defmethod (Igp-window-mixin :compute-right-x) () 
(setq right-x 

(fixr (* 0.5 (+ (» width scale-factor) 
(// top-edge 0.8)})))) 



;;; Calculates y-coord of top right point in LGP pixels. 
;;; Finds vertical length of figure in screen pixels by 
;;; dividing top edge by 0.8. Centers figure vertically 
;;; In window, correcting for higher density of LGP pixels. 
;;; This method shadows those of ARROW-PARAMETER-MIXIN and 
; ; ; BASIC-ARRGW-WINDOW-MIXIN . 
(defmethod (Igp-window-mixin :compute-top-y) () 
(setq top-y 

(fixr (» 0.5 (+ (» height scale-factor) 
(// top-edge 0.8)))})) 



Finally, we need to modify the coordinates used in the :shaw-Ilnes method 
to take account of the scale factor and the difference in origins for LGP 
and screen coordinates. We define new methods for :coi33pute-x and 
:compate-y to shadow the methods we defined for 
basic-arrow-window-mixin. 



;;; Converts x-coord of line endpoint from LGP to screen pixels. 
;;; Corrects for higher density of LGP pixels. This method shadows 
;;: that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-window-mixin :compute-x) (x) 
(fixr (// X scale-factor))) 



;;: Converts y-coord of line endpoint from LGP to screen pixels. 
;;; Corrects for higher density of LGP pixels and for screen origin 
;;; at top left. This method shadows that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-window-mixin :compute-y) (y) 
(fixr (- height (// y scale-factor)))) 
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We can now define the flavor we will actually instantiate with 
tv:make-window. This flavor, arrow-window, is just a combination of 
Igp-window-mixin and basic-arrow-window. 



(def flavor arrow-window () 

(Igp-window-mixin basic-arrow-window) 
( :documentation :conibination 
"Instantiable flavor for window output from LGP coordinates. 
This flavor has all the features of BASIC-ARROW-WINDOW but 
assumes that the calculation module uses LGP coordinates. This 
is the flavor to Instantiate for window output using the 
current calculation module.")) 



5.1.4 Flavors for LGP Output 

We want to be able to direct output to an LGP or an LGP record file as 
well as to a window. We define another flavor, Igp-pixel-Ksixin, to be 
mixed in with arrow-parameter-mixin. We can set an instance variable to 
the output stream and make it initable so that we can specify the output 
stream when we make an instance of the flavor we build on 
Igp-pixel-mixin. The output stream will itself be an instance of a flavor. 



(defflavor Igp-pixel-mixin 
(output-stream) 

() 

: initable- instance-variables 

( :required-f lavors arrow-parameter-mixin) 

( :documentation :mixin 
"Provides methods for arrow graphic output on an LGP stream. 
ARROW-PARAMETER-MIXIN is required to calculate the size of the 
figure and position it in the center of the page. The method 
assumes that coordinates are In LGP pixels. This flavor 
should be mixed, along with ARROW-PARAMETER-MIXIN, into an 
instantiable flavor for LGP output. When that flavor is 
instantiated, the instance variable output-stream should be 
initialized.")) 



The methods for this flavor need to do two things: determine the width 
and height of a page and handle :show-lines messages. We get the width 
and height from the values of instance variables for the flavor 
lgp:basic-lgp-stream. This flavor will be a component of the flavor we 
instantiate as the output stream. 
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Finds width and height of a page for LGP output. 
This flavor Is required by ARROW-PARAMETER-MIXIN. Finds the 
values of two Instance variables of LGP:BASIC-LGP-STREAM: 
SI:PAGE-WIDTH and SI: PAGE-HEIGHT. Assumes that 
LGP:BASIC-LGP-STREAM Is Included In output stream to provide 
these Instance variables, 
(defmethod (Igp-plxel-mlxln :compute-w1dth-and-height) {) 

(setq width (symeva1-1n-1nstance output-stream 'si :page-w1dth) 

height (symeval- In- Instance output-stream *s1:page-he1ght))) 



The :show-lines method is similar to that for windows. Instead of using 
the :draw-line message to produce lines, we use two messages to 
lgp:basic-lgp-streain: :send-command and :send-coordinates. 



Receives endpoint coordinates and draws lines on LGP stream. 
Arguments are alternating x- and y-coordlnates of endpolnts of 
lines to be drawn. If there are more than two pairs of 
coordinates, assumes that the endpoint of one line Is the 
starting point of the next. Draws a line by sending output 
stream :SEND-COMMAND messages for LGP commands and 
:SEND-COORDINATE messages for LGP coordinates. Assumes that 
flavor LGP:BASIC-LGP-STREAM Is Included In output stream to 
provide these methods, 
(defmethod (Igp-p1xel-m1x1n :show-11nes) 
(xO yO &rest x-y-pairs) 
;; Send command and coordinates to start drawing lines 
(send self ' :send-command-and-coord1nates #/m xO yO) 
;; "Cddr" down the list created by making all but the first 
;; pair of coordinates an &rest argument 
(loop for (x y) on x-y-paIrs by #'cddr 

;; Send command and coordinates to draw a line 

do (send self ':send-command-and-coord1nates #/v x y))) 



Sends line-drawing commands to LGP output stream. 

:SEM0-COMMAND transmits an LGP command. :SEND-COORDINATES 

transmits coordinates of an endpoint of a line to be drawn. 

Assumes that LGP:BASIC-LGP-STREAN Is included In output stream 

to provide these methods. 
(defmethod (lgp-pixel-mix1n :send-command-and-coordinates) (cmd x y) 
(send output-stream ':send-command cmd) 
(send output-stream ' :send-coord1nates (fixr x) (flxr y))) 



We can now define an instantiable flavor for the LGP stream that combines 
Igp-pixel-mixin and arrow-parameter-oiixin. 
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(defflavor Igp-plxel -stream () 

(Igp-pixel-mixln arrcw-parameter-nlxln) 
( :clocufflentat1on icombinatlon 
'Instantlable flavor for arrow output on LGP stream. 
Assumes that the calculation nodule uses LGP coordinates. 
When this flavor Is instantiated, the LGP-PIXEL-MIXIN 
Instance variable OUTPUT-STREAM should be initialized. 
The output stream can be directed to an LGP or a file, 
but it must include flavor LGP:BASIC-LGP-STREAM for 
output to work correctly.")) 



5.1.5 The Top-Level Function 

We are ready to define a top-level function we can call to produce the 
graphic. We start by popping up a choose-variable-values window. We 
allow the user to specify screen, LGP, or file output. We also allow the 
user to choose values for the number of recursion levels and the proportion 
of the page or window to be filled. We let the user decide whether or not 
to stripe the arrows. 

|(defvar »dest-str1ng* "Screen" 
"Destination of program output [Screen, LGP, or File]") 



(defvar •output-file* nil 

"Pathname for LGP-record-f lie output") 



Top-level function to call to produce arrow graphic. 
Pops up a choose-variable-values window to let user specify 
output destination, number of recursion levels, proportion 
of smaller dimension of page or window to be filled, and 
whether or not to stripe figure, 
defun do-arrow ( ) 
;; Pop up a choose-variable-values window 
(tv:choose-var1able-values 

'((•do-the-str1pes« "Stripe the arrows?" :boolean) 
(•max-depth* "Number of recursion levels" :number) 
(•fill-proportion* 

"Fraction of page or window to be filled" :number) 
(•dest-string* "Output destination" 

:choose ("Screen" "LGP" "File")) 
(•output-file* "Pathname for file output" :PATHNAME)) 
;; Hake window wide enough to accommodate long pathnames 
;; and error messages 
':extra-width 20. 
;; Give user a chance to abort 

':margin-choices '("Do It" ("Abort" (signal *sys:abort))) 
':label "Choose Options for Graphic")) 



Next we need to take action depending on the output destination the user 
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has chosen. If the variable •fill-proportion* is zero, we just return nil no 
matter what the output destination. If the destination is "Screen", we make 
an instance of arrow-window. We use tV:make-window, which creates a 
new window each time we call do-arrow. We could also have defined a 
resource of arrow windows (using defwindow-resource), but we might want 
more than one selectable arrow window at a time. 

If we have more than one arrow window, we want each to retain its own 
values for number of recursion levels, proportion of the window to be filled, 
and presence or absence of striping. We define three instance variables for 
basic-arrow-window-mixin and make them initable. We initialize them 
when we call tvzmake-window from do-srrow. We change the rafter 
daemons for basic-arrow-window-mixin to bind the special variables to the 
instance-variable values. 

(def flavor basic-arrow-window-mixin 
I (do-stripfes max-dep fill-prop) 

() 
I :initable-instance-variab1es 

( :requ1red-flavors arrow-parameter-mixin tv:window) 
(:default-init-plist 
:edges-froni *: mouse : mini mum-width 200 :min1mum-he1ght 200 
:blinker-p nil :expose-p t) 
(:docufflentation :mix1n ...)) 

(defmethod (basic-arrow-window-mixin :after :in1t) (ignore) 
I (let ((»fill-proportion» fill-prop)) 

(send self ':compute-parameters))) 

(defmethod (basic-arrow-window-mixin 

rafter :change-of-s1ze-or-marg1ns) (&rest ignore) 
I (let ((•fill-proportion* fill-prop)) 

(send self ':computo-parameters))) 

(defmethod (basic-arrow-window-mixin :after :refresh) 
(&opt1onal type) 
;; Draw figure if not restored from a bit-save array ... 
(when (or (not tv:restored-bits-p) 

;; ... or size has changed, 
(eq type *: Size-changed)) 
;; If restored from a bit-save array, clear screen first 
(when tv:restored-bits-p 

(send self ' :clear-screen)) 
:; Bind global variables to self and instance variables 
(let ((»dest» self) 

I(«do-the-stripes« do-stripes) 
(•max-depth* max-dep)) 
;; Draw the figure 
( draw-arrow-graph ic top-edge right-x top-y)))) 
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(defun do-arrow () 

(tv:choose-vari able-values 



;; If figure 1s Infinitely small, just return nil 
(cond ((= 'fm -proportion* 0) nil) 

;; If screen output, make a window 
((equal *dest-str1ng* "screen") 
(tv:i!iake-w1ndow 'arrow-window 

;; Initialize instance variables to 
;; values set by the user 
':do-stripes •do-the-str1pes« 
':inax-dep •max-depth* 
':fm-prop *fill-proport1on*)))) 



If the output destination is "LGP" or "File", we want to make an instance 
of Igp-pixel-stream with the instance variable stream initialized to an 
appropriate stream. We construct this stream by calling 
si:make~hardcopy-stream with an argument that depends on the output 
destination. We use with-open-stream to produce the output on the stream 
and close it when we finish. 
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(defun do-arrow () 

{tv:choose-var1able-values 



(cond ((= »fi11-proportion« 0) nil) 

;; If screen output, make a window 
((equal 'dest-string* "screen") 
(tv: make-window 'arrow-window 

;; Initialize Instance variables to 
;; values set by the user 
':do-str1pes *do-the-str1pes» 
':max-dep 'max-depth* 
':fm-prop *fm-proportion*)) 
;; If LGP or file output, use an appropriate stream 
(t (wlth-open-stream 
(stream 

;: This function returns a stream suitable for 

;; LGP output 

(si :make-hardcopy-streara 

;; Argument Is the output device. For LGP, 
;; use the default hardcopy device, 
(if (equal 'dest-string* "Igp") 
si :«d8fault-hardcopy-device* 
;; For file output, use the correct format 
;; for the hardcopy device and direct 
;; output to the file specified by the user 
(lgp:08t-lgp-record-fne-hardcopy-dev1ce 
•output-file*)))) 
;; Make an instance of our LGP output flavor 
(let ((»dest» 

(make-instance 'Igp-pixel-stream 

;; Initialize instance 
;; variable to output stream 
':output-stream stream))) 
;; Position the figure on the page 
(send «dest* ' :compute-parameters) 
;; Draw the figure, using Instance-variable values 
; ; as arguments 

(draw-arrow-graphic (send 'dest* ': top-edge) 
(send 'dest* ':r1ght-x) 
(send 'dest* ':top-y))))))) 



5.1.6 The Arrow Window: Interaction, Processes, and the Mouse 

Suppose we want to let the user modify the characteristics of the graphic 
for each window. The user might want to change the presence or absence 
of striping, the number of recursion levels, or the proportion of the window 
to be filled. 



One way to install this option is to associate each window with its own 
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process and let the process run in a loop. If the user clicks right on the 
window, we pop up a choose-variable-values window. When the user is 
finished, we refresh the window and wait for the next mouse click. 

We can associate a window with a process by including the flavor 
tvzprocess-misia in basic-arrow-window. When we make the window 
(using tv:make-window), we specify a :process init option whose argument 
is the name of the top-level function for the process. When the window is 
created, a new process is created as well. When the window is exposed, the 
process's top-level function is called with one argument, the window. 

(defflavor basic-arrow-window () 

(basic-arrow-window-mix In 
arrow-parameter -mixin 
tv:process-nix1n 
tv:window) 
(:documentat1on :combinat1on ...)) 

(defun do-arrow () 

(tv: choose-variable-values 



(cond ((= «f ill-proportion* 0) nil) 

;; If screen output, make a window 

((equal «dest-string» "screen") 
(tv:make-window 'arrow-window 

;; Initialize instance variables to 
;; values set by the user 
':do-stripes 'do-the-stripes* 
' :max-dep "max-depth* 
':fill-prop jyrill-proportion* 
;; Specify top-level function for the 
;; process associated with the window 
':process '(window-loop))) 



We next want to be able to handle mouse clicks. We include the flavors 
tv:any-tyl-iaixin and tvrlist-moHSe-buttons-mixin in basic-arrow-window. 

When a window is waiting for input and the mouse is clicked while over the 
window, a blip enters the window's input buffer. A blip is a list whose 
form, with tv:list-niouse-buttons-inixin, is as follows: 

(:mouse-button encoded-click window x y) 



Encoded-click is a fixnum that represents the button clicked. 



Program Development Tools and Techniques 



IJ9 



Symbolics, Inc. 



(defflavor basic-arrow-window () 

(baslc-arrow-wlndow-nlxln 
arrow-parameter-mlxin 
tv:any-ty1-mixin 
tvrllst-mouse-buttons-inlxln 
tv:process-m1x1n 
tv:window) 
( :documentat1on :coinb1nat1on )) 



We also want a mouse documentation string to appear when the mouse is 
over the window: 



(def method (baslc-arrow-wlndow-nlxln 

:who-11ne-documentat1on-str1ng} () 

"Provides a mouse documentation line for the window. 
The only option 1s to click right and pop up a 
choose-var1ab1e-va1ues window of options for changing 
the graphic on this window." 

"R: Choose-var1ab1e-va1ues options for changing figure on this window") 



We can now write the process function window-loop. This function just 
sends a :main-loop message to the window. We define :main-loop as a 
method for basic-arrow-window-mixin. The method consists of an 
error-restart-Ioop so that we can return to top level if sys:abort or an 
error is signalled. We send the window an :any-tyi message. If the user 
clicks right, we pop up a choose-variable-values window with the window's 
current value of the variables. When the user exits, we refresh the window 
and wait for another click. If the user aborts, sys:abort is signalled, and we 
restart the loop. 



Top-level function for process associated with arrow window. 
The function Is called when the window is created. Argument Is 
the window. The function sends the window a :MAIN-LOOP message. 
This method should be the actual command loop for the process, 
(defun window-loop (window) 
(send window *:ma1n-loop)) 
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Command loop for window associated with a separate process. 
Consists of an error-restart-lOop that handles restarts from errors 
and sys:abort. Walts for mouse Input. If a right click, pops up a 
choose-var1ab1e-va1ues window to change characteristics of the 
figure. On exit, sets Instance variables to the new values and 
refreshes the window, then waits for another mouse click. Assumes 
blips are lists of the form provided by TV:LIST-HOUSE-BUTTONS-MIXIN. 
(defmethod (basic-arrow-wlndow-mixin :ma1n-1oop) () 

;; Run forever in a loop. Offer a restart handler if an error 
;; or SYS:ABORT is signalled. 

(error-restart-loop ((error sys:abort) "Arrow Window Top Level") 
; ; Wait for input 
(let ((char (send self ':any-ty1))) 

;; Pop up window if input is a list ... 
(when (and (listp char) 

;; and a mouse click 

(eq (first char) ' :mouse-button) 
;; ... and a single click on the right button, 
(eq (second char) #\mouse-r-l)) 
;; Bind global variables to instance-variable values 
(let ((»do-the-stripes« do-stripes) 
(«max-depth» max-dep) 
(•fill-proportion* fill-prop)) 
;; Pop up a choose-variable-values window 
(tvrchoose-varlable-values 

'((»do-the-stripes* "Stripe the arrows?" :boolean) 
(•max-depth* "Number of recursion levels" :number) 
(•fill-proportion* 

"Fraction of window to be filled" rnumber)) 
;; Make the window wide to provide enough room for error 
; ; messages. 
':extra-width 20 

; ; Give the user a chance to abort 

':marg1n-choices '("Do It" ("Abort" (signal 'sys:abort))) 
': label "Choose Options For Graphic") 
;; Set instance variables to the new values 
(setq do-stripes «do-the-stripes« 
max-dep »max-depth« 
fill-prop •fni-proportion») 
;; Recompute size and position of the figure 
(send self ' :compute-parameters) 

;; Send :REFRESH message with argument of ':new-vals to make 
;; sure the figure is redrawn if there is a bit-save array 
(send self ' :refresh ' :new-vals))))) ) 



We need to change the :after rrefresh method for 
basic-arrow-window-mixiii so that it redraws the figure when the values 
are changed even if the window has a bit-save array. 
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(defmethod (bas1c-arrow-window-raix1n :after :refresh) 
(&opt1ona1 type) 
;; Draw figure If not restored froai a bit-save array ... 
(when (or (not tv:restored-bits-p) 

;; ... or size has changed ... 
(eq type ':size-changed) 
;; ... or new values for figure parameters, 
(eq type ':new-va1s)) 
;; If restored from a bit-save array, clear screen first 
(when tv:restored-bits-p 

(send self ':c1ear-screen)) 
;; Bind global variables to self and Instance variables 
(let ((»dest« self) 

(»do-the-stripes* do-stripes) 
(•max-depth* max-dep)) 
;; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 

Note that we can also manipulate the windows we create by using the 
[Split Screen] and [Edit Screen] options from a system menu. We might 
have more than one arrow window on the screen at the same time. We 
might redisplay the figures on these windows at the same time. In this case, 
the scheduler might switch between the arrow window processes, allowing 
each to run for a time until all redisplays are complete. 

Remember that we took care to bind rather than set the global variables in 
the calculation module that hold the state of each arrow. We want the 
values of some variables to be different in each window. Each process 
maintains its own bindings for variables. When the scheduler switches 
processes, bindings in the old process are undone and saved. They are 
restored when the old process resumes. But if we had set the variables, the 
program would not have run correctly when the scheduler switched 
processes. The new process might have used variable values set in the old 
process. 



5.1.7 Signalling Conditions 

We want to add one more refinement to the output module. In our cfaoose- 
variable-values windows, the variable type keywords, such as :number and 
:pathname, provide for some error checking when users choose new values. 
But two of our numeric variables have further restrictions: *max-depth* 
must be a nonnegative integer, and •fill-proportion* must be a fraction 
between and 1. 

The function tv:choose-variable-values has a :function option that lets us 
name a function to be called whenever an item is to be changed. We can 
use this function to check the values of our two variables and signal a 
condition if the values are bad. We then print a message on the window 
and ask the user to proceed by supplying a new value. 
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We start by defining flavors for the conditions we signal. We define a 
general class of error conditions called bad-arrow-variable. We then define 
two flavors built on bad-arrow-variable: bad-arrow-depth for improper 
values of *max-depth« and bad-arrow-fill-proportion for improper values 
of *fill-proportion*. For each of these instantiable flavors we define a 
:report method and a :proceed method. The :report method prints a 
string identifying the condition. The :proceed method allows the user to 
proceed from the condition, in this case by supplying a new value. We 
could have more than one :proceed method if we had other ways of 
proceeding. :proceed methods are combined using :case method 
combination. 

If we want to create conditions for bad values of other variables in the 
future, we can simply define new flavors built on bad-arrow-variable. 

(defflavor bad-arrow-variable () (error) 
( :documentat1on 

■Nonlnstantlable class of bad-variable conditions. 
The user might set some variables to Impermissible values. 
These conditions are to permit checking for bad values 
beyond the system's error checking. Instantiable condition 
flavors for specific variables should be built on this 
flavor.")) 



(defflavor bad-arrow-depth () (bad-arrow-variable) 
( idocumentation 
"Proceedable condition: bad value for »MAX-OEPTH*. 
An instantiable condition flavor for impermissible values 
of »MAX-DEPTH«, the number of recursion levels In the 
figure.")) 

;;; Prints string on stream to report bad »MAX-DEPTH» value 
(defmethod (bad-arrow-depth :report) (stream) 
(format stream "No. of levels was not a " 
nonnegative fixnum.")) 

;;; Proceed type method for supplying new value of *MAX-DEPTH* 
(defmethod (bad-arrow-depth :case rproceed :new-depth) 
(Sioptional (dep (prompt-and-read 
' : number 

"Supply new value for ~ 
no. of recursion levels: "))) 
"Supply a new value for number of recursion levels." 
(values ':new-depth dep)) 
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(defflavor bad-arrow-f ill-proportion () (bad-arrow-variable) 
( rdocumentation 
"Proceedable condition: bad value for *FILL-PROPORTION«. 
An instantiable condition flavor for irapermissible values of 
•FILL-PROPORTION* , the fraction of the smaller dimension of 
the page or window that the figure is to fill.")) 

;;; Prints string on stream to report bad "FILL-PROPORTION* value 
(defmethod (bad-arrow-fill-proportion :report) (stream) 
(format stream "Proportion was not a fraction between ~ 
and 1.")) 



; ; ; Proceed type method for new value of »FILL-PROPORTION« 
(defmethod (bad-arrow-f ill -proportion :case :proceed 

:new-proport1on) 
(&optional (prop (prompt-and-read 
' : number 

"Supply new fraction of bounds <- 
be filled: "))) 
"Supply a new fraction of page or window to be filled." 
(values ' :naw-proport1on prop)) 



Next we write the function, check-item, to be called when a variable value 
is changed. The function is called with four arguments: the choose- 
variable-values window, the variable, and the variable's old and new values. 
We use condition-bind to bind a handler for our two conditions. This 
handler will be called if we signal the conditions from within the 
condition-bind. If we do find a bad variable value, we we expect the call 
to signal to return the two values from the :proceed method: the proceed 
type and the new variable value. We then check the new value and, if it is 
good, set the variable to the new value. Finally, we refresh the window and 
return t. 
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Called when a value changes 1n choose-variable-values window. 
Arguments are the window, the variable, and Its old and new values. 
Binds handlers for conditions for Impermissible values. If new 
value Is OK, sets variable to the new value, refreshes window, and 
returns t. If value is not OK, signals the appropriate condition. 
When SIGNAL returns, presumably with a new variable value, checks 
the new value In the same way It checks a new value that cones 
from the window, 
(defun check-Item (cvv-wlndow var old-val new-val) 

We don't use the old value. To avoid a compiler complaint. 
Just evaluate It and ignore it. We could also use IGNORE 
instead of OLD-VAL in the arglist, but then the arglist 
would be less meaningful, 
old-val 

;; Bind handlers for the conditions we might signal 
(condition-bind ((bad-arrow-depth 'bad-arrow-var-handler) 
(bad-arrow-flll -proportion 
' bad-arrow-var-handl er ) ) 
(when (eq var '»max-depth») 

;; •MAX-DEPTH* must be nonnegatlve fixnum 
(loop until (and (fixp new-val) (i new-val 0)) 

If It's not, bind QUERY-IO to the window and 
signal a condition. SIGNAL should return 
two values, the proceed type and the new 
value from the proceed method. Ignore the 
proceed type and set KEW-VAL to the new 
value, 
do (let ((query-1o cvv-window)) 

(multiple-value (nil new-val) 
(signal 'bad-arrow-depth))))) 
(when (eq var '•f111-proportion«) 

;; »FILL-PROP0RTI0M« must be between and 1 
(loop until (and (i new-val 0) (S new-val 1)) 

;; If it's not, bind QUERY-IO to the window and 
;; signal a condition. SIGNAL should return 
;; two values, the proceed type and the new 
;; value from the proceed method. Ignore the 
;; proceed type and set KEW-VAL to the new 
;; value, 
do (let ((query-io cvv-window)) 

(multiple-value (nil new-val) 

(signal 'bad-arrow-fill-proportion))))) 
;; Variable value is now OK. Set variable to the new value. 
;; Note that we DO want to evaluate VAR. 
(set var new-val ) 
;; Refresh the window 
(send cvv-window ':refresh) 
;; Return t 
t)) 



Next we need to add the rfunction option to our calls to 
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tv:choose-variable-vaIues in the function do-arrows and the :Btain-loop 
method of basic-arrow-window-mixin: 



(defun do-arrpw () 

;; Pop up a choose-varlabTe-values window 
(tv:choose-var1ab1e-va1ues 

'((•<lo-the-str1pes» "Stripe the arrows?" :boo1ean) 
(•max-depth* "Number of recursion levels" inumber) 
(•fin-proportion* 

"Fraction of page or window to be filled" :number) 
(•dest-string* "Output destination" 

:choose ("Screen" "LGP" "File")) 
(«output-f11e» "Pathname for file output" ipathname)) 
; Nake window wide enough to accoiRfliodate long pathnames 
; and error messages 
:extra-w1dth 20. 

; Call this function when a value Is changed 
':funct1on 'check-Item 

Give user a chance to abort 
':marg1n-cho1ces '("Do It" ("Abort" (signal 'sysrabort))) 
: label "Choose Options for Graphic") 
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(defmethod (baslc-arrow-window-raixln :ma1n-loop) () 

;; Run forever In a loop. Offer a restart handler if an error 
;; or sys:abort 1s signalled. 

(error-restart-loop ((error sys:abort) "Arrow Window Top Level") 
;; Wait for Input 
(let ((char (send self ':any-ty1))) 

;; Pop up window if input is a list ... 
(when (and (listp char) 

;; and a mouse click — 

(eq (first char) ':mouse-button) 

;; and a single click on the right button. 

(eq (second char) #\mouse-r-l)) 
;; Bind global variables to instance-variable values 
(let {(»do-the-stripes« do-stripes) 
(•max-depth» max-dep) 
(•fill-proportion* fill-prop)) 
;; Pop up a choose-variable-values window 
(tv:choosQ-var1 able-values 

'((•do-the-stripes« "Stripe the arrows?" rboolean) 
(•max-depth« "Number of recursion levels" rnunber) 
(♦fill-proportion* 

"Fraction of window to be filled" rnumber)) 
;; Hake the window wide to provide enough room for error 
; ; messages. 
':extra-w1dth 20 

;; Call a function to check for errors when values change 
':funct1on 'check-item 
;; Give the »&er a chance to abort 

':marg1n-choic6S '("Bo It" ("Abort" (signal 'sysrabort))) 
': label "Choose Options for Graphic") 
;; Set instance variables to the new values 
(setq do-stripes »do-the-str1pes* 
max-dep *max-depth* 
fill-prop «f ill-proportion*) 
;; Recompute size and position of the figure 
(send self ' :compute-parameters) 

;; Send :REFRESH message with argument of ':new-vals to make 
;; sure the figure is redrawn if there is a bit-save array 
(send self 'irefresh ':new-vals)))))) 

Finally, we need to write a handler for the two conditions. When a 
condition is signalled, the handler is called with one argument, the object of 
the flavor of condition that is signalled. In check-item, we call signal with 
query-io bound to the choose-variable-values window. The handler checks 
to be sure there is a proceed type for the object. If so, the handler turns 
on a blinker on the window and sends the rreport and :proceed messages to 
the condition object. Finally, it turns off the blinker and passes back to its 
caller the two values that the :proceed method returns. 
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Actually, the handler we define doesn't depend on the binding of qnery-io 
to the window. If query-io is not bound to a window — that is, to an 
instance of a flavor built on tv:sheet — the handler won't try to turn on a 
blinker. If query-lo is bound to a window, the handler first looks (using 
tT:sheet-folloving-blinker) for an existing blinker that follows the cursor. 
If it doesn't find one, it makes a nev/ blinker (using tvrmake-blinker). It 
encloses the handling operation in an unwind-protect to be sure that the 
blinker is turned off in case of a nonlocal exit. 



; Handler for bad value of »MAX-DEPTH» or *FILL-PROPORTION». 
; Argument is the condition object created by SIGNAL. Uses QUERY-IO 
; stream to report condition. Sends the condition object a rPROCEED 
; message and passes back the values it returns, 
(defun bad-arrow-var-handler (cond-obj &aux bl) 

;; Find out whether this object has the right proceed type. 

:; If not, return nil. 

(if (send cond-obj ' :proceed-type-p 

(cond ((typep cond-obj 'bad-arrow-depth) ':new-depth) 
((typep cond-obj 'bad-arrcw-flll-proportion) 
' :new-proportion))) 
;; Enclose the handling operation in an UNWIND-PROTECT so that 
;; if we use a blinker we are sure to turn it off 
(unwind-protect 
(progn 

;; Use a blinker if the QUERY-IO stream is a window 
(setq bl (If (typep query-io 'tv:sheet) 

;: If a cursor-following blinker exists, use It 
(or (tvrsheet-following-bl inker query-io) 
;; Otherwise, make a new blinker 
(tv:make-b1 Inker query-io 

'tv:rectangular-bl Inker 
':fonow-p t)))) 
; ; If a blinker, make it blink 
(if bl (send bl ' :set-v1s1bnity ':bl1nk)) 
;; Alert the user 
(tv:beep) 

;; Send a report, presumably describing the condition 
(send cond-obj 'treport query-io) 

;; Send object a :PROCEED message and return the values 
; ; that the method returns 
(send cond-obj ': proceed 

(cond ((typep cond-obj 'bad-arrcw-depth) 'rnew-depth) 
((typep cond-obj 'bad-arrow-fill-proportion) 
':new-proport1on)))) 
;; If a blinker, turn it off 
(if bl (send bl ':set-vis1b11ity nil))))) 



After we have defined all the flavors and methods for the output module, 
we insert a compile-flavor-methods form in the file. Without this macro, 
combined methods are compiled and flavor data structures generated when 
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we make the first instance of a flavor — that is, at run time. 
compile-flavor-methods speeds run-time operation by causing combined 
methods to be compiled at compile time and data structures to be generated 
at load time. It is useful only for flavors that will be instantiated, not for 
flavors that are only components of instantiated fla%'ors. 

(compile-flavor-methods arrow-window Igp-pixel-stream 

bad-arrow-depth bad-arrow-fill-proportion) 



5.2 Programming Aids for Flavors and Windows 

Some editor commands and Lisp functions provide information about flavors. You can find out 
about component flavors, methods, instance variables, init keywords, and documentation. Using 
the Inspector, you can examine instance variables and methods for instances of flavors (see 
section 4.7, page 94). If a flavor has gettable instance variables, you can obtain their values by 
sending messages to instances of the flavor. 

These commands and functions are useful for finding information about windows as well. 
Because windows are instances of flavors, you can retrieve characteristics that are stored in 
gettable instance variables by sending messages to the windows (see Introduction to Using the 
Window System). If a window is exposed, you can examine and alter some characteristics by 
clicking on the [Attributes] item in the system menu. Clicking on [Attributes] pops up a 
choose-variable-values window for such characteristics as font, label, margins, and vertical 
spacing between lines. 

As with other definitions. Edit Definition (m-.) prepares to edit definitions of flavors and 
methods. Section 5.2.2 (page 129) describes how to use this command to edit method 
definitions. 



5.2.1 General Information 

The facilities that display general information about a flavor are Describe 
Flavor (m-X) and descrlbe-flavor. These display somewhat different 
descriptions of a flavor. 

A useful predicate for instances of flavors is typep. Given an instance and 
a flavor name, typep returns t if the instance includes the flavor as a 
component. 

Example 

In handling bad values for the variables *max-depth* and 
♦fill-proportion*, we want to be sure that query-io is bound to a window 
before turning on a blinker. We find out whether the object bound to 
query-io is built on tv:sheet by using typep: 

(typep query-io 'tv: sheet) 
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Reference 
Describe Flavor (m-X) 



(describe-flavor fJavor-nami) 



(typep arg type) 



Displays a description of a flavor that 
includes the names of instance 
variables and component flavors and 
any documentation added by the 
:document&tion option to defflavor. 
Also displays init keywords and 
inherited methods and instance 
variables. Names of flavors and 
methods in the display are mouse 
sensitive. 

Prints a description of a flavor that 
includes the names of instance 
variables and component flavors and 
any documentation added by the 
:documentatlon option to defflavor. 

When arg is an instance of a flavor 
and type is a flavor name, returns t if 
the instance includes the flavor as a 
component or nil if it does not. If 
type is omitted, returns a symbol 
representing the flavor of the 
instance. 



5.2.2 Methods 



Four Zmacs commands display information about the methods that handle 
messages to instances of flavors. For instances of flavors built on 
si:vanilla-flavor — that is, for nearly all flavors — you can send messages 
to find out which messages the object handles and whether or not it handles 
a specific message. 

You can use the Zmacs command Edit Definition (m-.) to edit the 
definition of a method. Specify a method by typing a representation of its 
function spec. This is a list of the following form: 



(:method flavor type message) 



When typing this representation for Edit Definition (m-.). type is optional. 
If the method has a type, Zmacs will try to find the definition and ask you 
whether or not that definition is the one you want. 

You might know the name of a method but not the name of its flavor. Use 
List Methods (m-X) to find methods for all flavors that handle a message. 
You can click on one of the method names displayed to edit its definition. 
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Example 

We want to edit the definition of the :maIn-loop method for 

basic-arrow-window-mixin. We use Edit Definition (m-.) and type: 

(:method baslc-arrow-wlndow-nixin :ma1n-1oop) 



Example 

We want to find out which methods handle :show-lines messages and how 

the methods handle the messages. List Methods (tn-X) displays the following 

methods: 

Methods for :SHOW-LINES 

(iMETHOD BASIC-ARROW-WINDOW-MIXIM :SHOW-LINES) 

(:METHOD LGP-PIXEL-HIXIN :SHOW-LINES) 

We can click on one of the method names or press c-. to edit the 
definition. We also could have found the source code directly by using Edit 
Methods (m-X). 



Example 

We want to find out which methods are called when the system sends an 
:lnit message to arrow-window. List Combined Methods (m-X) prompts for 
message and flavor names and displays the foUovidng methods, in the order 
in which they are called: 

Combined method for :INIT message to ARROW-WINDOW flavor 

(:METHOD TV:SHEET :WRAPPER :INIT) 

(rHETHOO TV:STREAM-MIXIN :BEFORE :INIT) 

(iMETHOD TV:BORDERS-HIXIM iBEFORE :INIT) 

(:METHO0 TV:ESSENTIAL-L.ABEL-MIXIM :BEFORE :INIT) 

(: METHOD TV: ESSENTIAL-WINDOW : BEFORE :INIT) 

(:METHOD TV:SHEET :INIT) 

(:METHOD TV:ESSENTIAL-SET-EDGES :AFTER :INIT) 

(:METHOD TV:LABEL-HIXIN :AFTER rINIT) 

(:METHOD TV:PROCESS-MIXIN :AFTER :INIT) 

(:METHOD BASIC-ARROW-WINDOW-MIXIN :AFTER :INIT) 



Reference 

List Methods (m-X) Lists methods for all flavors that 

handle a specified message. Press c-. 
to edit the definitions of the methods 
listed. 

Edit Methods (m-X) Prepares to edit definitions of 
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List Combined Methods (m-X) 



Edit Combined Methods (m-X) 



methods for all flavors that handle a 
specified message. Press c-. to edit 
subsequent definitions. 

Lists all the methods that would be 
called if a specified message were sent 
to an instance of a specified flavor. 
Press C-. to edit the definitions of 
the methods listed. 

Prepares to edit definitions of 
methods that would be called if a 
specified message were sent to an 
instance of a specified flavor. Press 
C-. to edit subsequent definitions. 

(send instance ':which-operations) Returns a list of messages that 

instance can handle. 

(send instance ':operation-handIed-p message) 

Returns t if instance has a handler for 
message or nil if it does not. 

Returns the method that handles 
message to object, or nil if object has 
no handler for message 



(get-handler-for object message) 



5.2.3 Init Keywords 

5l:flavor-allowed-init-keywords retrieves the init keywords allowed for a 
flavor. 

Example 

We want to find the allowed init keywords for Igp-pixel-streara. 

si:flavor-allowed-init-keywords returns the following list: 

(:DO-STRIPES :FILL-PROP :MAX-DEP : OUTPUT-STREAM) 

These are all keywords for initable instance variables, the first three from 
arrow-parameter-mixin and the last from Igp-pixel-mixin. 



Reference 
(5i:flavor-allowed-init-keywGrds flavor-name) 

Returns a list of any init keywords a 

flavor can take. 
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Appendix A 
Calculation Module for the Sample Program 



The program used as an example in this document draws the recursive arrow graphic on the 
document's cover. This appendix contains Lisp code that calculates coordinates for the 
endpoints of the lines that compose the figure. The code produces output by sending messages 
to instances of flavors defined in another file. Appendix B (page 147) contains the code for 
the flavors and methods that mediate between the program and the system output operations. 
Appendix C (page 165) contains a reproduction of the LGP graphic the program produces. 



> f > 



-*- Mode: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 
Copyright (c) 1983 Symbolics, Inc. 



#1 

This file contains the calculation module for a program that 
reproduces the recursive arrow graphic printed on the covers 
of most Symbolics documents. The module calculates the 
coordinates of the endpoints of line segments to be drawn. 
It transmits these coordinates to a separate output module, 
which contains the code needed to produce the figure on an 
appropriate output device. 

We use paper coordinates, origin at bottom left. 

Each arrow In the figure can be seen as Inscribed In a square 
whose apex Is at (apex-x, apex-y). Each arrow has a head and 
a shaft. Top-edge Is the top edge of each arrow, one of the 
sides of the arrowhead. There are two classes of arrow in 
the figure: The small arrows are the general case, and the 
large, outer arrow is unique. The differences are the 
structures of the shafts and the recursive appearance of 
the small arrows. 

The module uses special variables to store information about 
the current arrow, including the length of the top edge and 
the coordinates of the vertexes. 

The module first calculates coordinates for the vertexes of 
the large, outer arrow. If the arrows are to be striped, it 
determines the endpoints of the lines that make up the large 
arrow's stripes, first in the head and then in the shaft. 
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The module then recursively calculates coordinates for each of 
the small arrows Inside the figure. It outlines and stripes 
one arrow at a time. For each arrow, the module first 
calculates the coordinates of the vertexes of the head. If the 
arrows are to be striped. It then determines the coordinates of 
the endpolnts of the lines that make up the current arrow's 
stripes, first In the head and then In the shaft. 

The output module Initiates the calculation module by calling 
DRAW- ARROW-GRAPHIC with three arguments: the length of the 
figure's top edge and the coordinates of the top right point 
(pO in the large arrow). This module transmits coordinates to 
the output module by sending :SHOW-LINES messages to Instances 
of output flavors. The arguments to :SHOW-LINES are the 
coordinates of the endpolnts of lines to be drawn. The current 
Instance of the output flavor is the value of the special variable 
•DEST». 

(apex-x, apex-y) 
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Points 3 and 4 are obscured, except In the case of the big arrow. 
I# 



;;; Following are declarations for special variables and constants 

(defconst *dl* 0.15 

"Proportion of distance filled In between upper right stripes") 

(defconst •d2* 0.75 
"Proportion of distance filled in between lower left stripes") 

(defconst *str1pe-d1stance* 20 
"Horizontal distance In pixels between stripes of large arrow") 

(defconst *max-depth* 7 

"Number of levels of recursion") 

(defconst 'do-the-strlpes* t 
"If T, permits striping") 

(defconst *dest* nil 
"Object to which output Is sent") 

(defvar 'depth* 

"Current level of recursion") 

(defvar *top-edge* nil 
"Length of the top edge of the arrow") 

(defvar *top-edge-2* nil 
"Half the length of the top edge of the arrow") 

(defvar •top-edge-4* nil 
"One-fourth the length of the top edge of the arrow") 

(defvar •x2» nil 
"X-coord of projection of lower left stripe on top edge") 

(defvar *str1pe-d* nil 
"Horizontal distance In pixels between stripes') 

(defvar 'pOx* nil 
"X-coordlnate of the tip of the arrow") 

(defvar *pOy» nil 
"Y-coordlnate of the tip of the arrow") 

(defvar »plx« nil 
"X-coordlnate of point pi In the arrow") 
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(defvar 'ply* nil 
"Y-coordinate of point pi in the arrow") 

(defvar »p2x* nil 
"X-coordlnate of point p2 In the arrow") 

(defvar 'pZy* nil 

"Y-coordinate of point p2 In the arrow") 

(defvar 'pSx* nil 

"X-coordlnate of point p3 In the arrow") 

(defvar 'pSy* nil 

"Y-coordinate of point p3 In the arrow") 

(defvar •p4x* nil 

"X-coord1nate of point p4 In the arrow") 

(defvar •p4y* nil 
"Y-coordinate of point p4 In the arrow") 

(defvar *p5x« nil 
"X-coordinate of point p5 In the arrow") 

(defvar "pSy* nil 

"Y-coordinate of point p5 in the arrow") 

(defvar »p6x» nil 

"X-coordlnate of point p6 in the arrow") 

(defvar 'pey* nil 

"Y-coord1nate of point p6 In the arrow") 



;;; Following are the controlling functions for this module 



Program Development Tools and Techniques 137 

Symbolics, Inc. 



Function controlling the calculation module. 

Controls the calculation of the coordinates of the endpoints of the 
lines that make up the figure. The three arguments are the length of 
the top edge and the coordinates of the top right point of the large 
arrow. DRAW-ARROW-GRAPHIC calls DRAW-BIG-ARROW to draw the large arrow 
and then calls DO-ARROWS to draw the smaller ones, 
(defun draw-arrow-graphic (•top-edge* "pOx* 'pOy*) 
;; Bind global variables 
(let ((*top-edge-2» (// 'top-edge* 2)) 
(*top-edge-4* (// 'top-edge* 4)) 

;; Compute horizontal distance between stripes in the large 
;; arrow, assuming 64 stripes in the large arrowhead. 
(*stripe-distance* (// *top-edge» 64))) 
(draw-big-arrow) ;Draw large arrow 

Length of the top-edge for the first small, arrow is half the 
length for the large arrow. Bind new coordinates for the top 
right point of the small arrow, 
(let ((«top-edge* »top-edge-2») 

(«pOx« (- 'pOx* *top-edge-2*)) 
(*pOy* (- *pOy» •top-edge-2*)) 
(•depth* 0)) 
(do-arrows)))) ;Draw small arrows 

Recursive function controlling drawing of the small arrows. 
If below the maximum recursion level, draws a small arrow. Binds 
new values for depth, top edge, and coordinates of top right point, 
and calls self recursively to draw a left-hand child arrow. Binds 
special variables again and calls self to draw a right-hand child 
arrow, 
(defun do-arrows ( ) 

;; Don't exceed maximum recursion level 
(when (< *depth* *max-depth*) 

;; Bind values for half and one-fourth of top edge 
(let ((*top-edge-2* (// 'top-edge* 2)) 
(*top-edge-4« (// 'top-edge* 4))) 
(draw-arrow) ;Draw a small arrow 

;; Increment depth. Divide top edge in half. Bind new 
;; coordinates for top right point of next arrow, 
(let (('depth* (1+ 'depth*)) 

(•top-edge* *top-edge-2*) 
(*pOx* (+ •top-edge-4* (- *pOx* «top-edga*))) 
(•pOy* (- «pOy* *top-edge-4*))) 
;; Draw a left-hand child arrow 
(do-arrows)) 
;; Increment depth. Divide top edge in half. Bind new 
;; coordinates for top right point of next arrow, 
(let ((*depth* (1+ *depth*)) 

(*top-edge* •top-edge-2*) 
(*pOx* (- *pOx* *top-edge-4*)) 
(*pOy* (♦ *top-edge-4* (- *pOy» 'top-edge*)))) 
;; Draw a right-hand child arrow 
(do-arrows))))) 
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;;; The following functions are common to the large and small arrows 

Calculates coordinates of points visible in large and small arrows. 
The four points that bound the head of each arrow are the only ones 
visible in the small arrows. Points 3 and 4 -- the base of the arrow 
-- are obscured, except in the large arrow. We calculate these in 
compute-arrow-shaft-points, 
(defun compute-arrowhead-points () 
(let* ((plx (- "pOx* »top-edge»)) 

(ply 'pOy*) 

{p2x (+ plx •top-edge-4*)) 

(p2y (- "pOy* •top-edge-4»)) 

(p6x 'pOx*) 

(p6y (- »pOy« »top-edge*)) 

(p5x (- »pOx« •top-edge-4*)) 

(p5y (+ p6y *top-edge-4»))) 
(values plx ply p2x p2y p5x p5y p6x p6y))) 

Calculates horizontal distance between stripes. 
Distance is a fraction of the distance between stripes for the 
large arrow. The divisor depends on the level of recursion. 
Distance divides length of top edge evenly when possible to 
maintain continuity between head and shaft of arrow, 
(defun compute-stripe-d () 

;; Distance should be at least 3 pixels so that there Is some 
;; white space between lines, 
(if (S 'stripe-distance* 3) 3 

;; First find a fraction of *STRIPE-DISTANCE« that depends 
; ; on recursion level 

(loop for dist = (fixr (// •stripe-distance* 

(selectq *depth* 
(0 2) 
(1 4) 
(2 2) 
(3 1.5) 
(4 1.5) 

(otherwise 2)))) 
;; Increment if it doesn't divide *TOP-EDGE* evenly 
then {U dist) 

when (= (\ 'top-edge* dist)) 
;; Stop when no remainder. Don't return a value 
; ; less than 3. 
do (return (if (i dist 3) 3 dist))))) 
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;;; Calculates the number of lines that compose each stripe. 
;;; Calls COMPUTE-DENS to calculate the proportion of distance 
;;; between stripes to be filled, then multiplies by the actual 
;;; distance between stripes. Hakes sure that there is at least 
;;; one line and that there aren't too many lines to leave some 
;;; white space, 
(defun compute-nlines (x) 

;; Call COMPUTE-DENS and multiply result by »STRIPE-D« 
(let ((nl (fix (• •str1pe-d« (compute-dens x))))) 
;: Supply at least one line 
(cond ((£: nl 1) 1) 

;; But leave some white space between lines 
((2 nl (- »stripe-d« 1)) (- »stripe-d« 2)) 
(t nl)))) 

;;; Calculates proportion of distance filled in between each stripe. 
;;; The argument is the x-coordinate of the projection of the current 
:;; stripe onto the line formed by the top edge. Determines where the 
;;; projection of the current stripe is on this line In relation to the 
;;; distance from first to last stripes in the arrow. Multiplies this 
;;; fraction by the difference between densities of first and last 
:;; stripes. Finally, adds the density of the first stripe, 
(defun compute-dens (x) 
(+ 'dl* (• (- •62* 'dl*) 

(// (- X "pOx*) (float (- 'xZ* 'pOx*)))))) 



:;; The following two functions stripe the arrowheads. The 
;;; heads of the large and small arrows are Identical, so we 
;;; use the same functions to stripe both. 

;:; Function controlling striping of the head of each arrow. 
;;; Determines coordinates of starting and ending points for each 
;;; stripe. Calls COMPUTE-NLINES to determine number of lines for 
;:: the stripe. Calls DRAW- ARROWHEAD- LINES to draw the lines that 
;;; make up each stripe, 
(defun stripe-arrowhead () 

;; Find x-coord of top of last stripe to be drawn 
(loop with last-x = (- 'pOx* 'top-edge') 

;; Find starting x-coord for each stripe, decrementing 

;; by distance between stripes. Stop at last x-coord. 

for start-x from *pOx» by "stripe-d* above last-x 

;: Find ending y-coord for each stripe, decrementing by 

;; distance between stripes. 

for end-y downfrom »pOy* by "stripe-d* 

;; Find number of lines in the stripe 

for nlines = (compute-nlines start-x) 

;; Draw the lines that make up the stripe 

do (draw-arrowhead- lines nlines start-x end-y last-x))) 
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Draws the lines that make up each stripe in an arrowhead. 
Arguments are number of lines in the stripe, starting x-coord 
and ending y-coord of first line, and x-coord of top of last 
stripe to be drawn. Decrements by one pixel when drawing each 
line. 

(defun draw-arrowhead- lines (nlines start-x end-y last-x) 
; ; Set up a counter 
(loop for i from below nlines 

;; Find starting x-coord, subtracting counter from first 

; ; x-coord 

for first-x = (- start-x 1) 

;; Hake sure we don't go past the end of the arrowhead 

while (< last-x first-x) 

;; Draw a line 

do (send «dest* ': show- lines 

first-x "pOy* 'pOx* (- end-y i)))) 



The following functions draw and stripe the large arrow 

Function controlling drawing of the largo arrow. 
Calls functions to find coordinates of vertexes of the arrow. 
Outlines the arrow. Binds distance between stripes and x-coord 
of projection of last stripe onto top edge. Finally, stripes 
head and shaft of arrow when required, 
(defun draw-big-arrow () 

;; Determine coordinates of arrowhead vertexes 
(fflultiple-value-bind 

(•plx* »ply» *p2x« *p2y« *p5x» »p5y* »p6x« 'pey*) 

(compute-arrowhead-points) 
;; Determine coordinates of shaft vertexes 
(multiple-value-bind 

(•p3x* «p3y« »p4x» «p4y») 

(compute-arrow- shaft-points) 
(draw-big-outline) :Outline arrow 

(when •do-the-stripes» 

;; Bind distance between stripes and x-coord of projection 
;; of last stripe onto top edge 
(let ((»stripe-d« •str1pe-distance») 

(•x2« (- 'pOx* »top-edge» 'top-edge*))) 
(stripe-arrowhead) ;Stripe head 

(str1pe-b1g-arrow-shaft)))))) ;Str1pe shaft 

;;; Calculates coordinates for vertexes of shaft of large arrow. 

;;; These points are obscured and not drawn for the small arrows. 

(defun compute-arrow-shaft-points () 

(values (- 'plx* nop-edge-4«) ;X-coord of point 3 

(- "pZy* •top-edge-2«) ;Y-coord of point 3 

»p2x» ;X-coord of point 4 

(- •p2y« »top-edge»))) ;Y-coord of point 4 
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;;; Draws the outline of the large arrow. 

(defun draw-big-outline () 
(send "dest* ':show-11nes 

•pOx» "pOy* 'plx* "ply* 'pZx* •p2y» 'pSx* «p3y« 
•p4x» »p4y» «p5x« »p5y« 'pex* "pGy* 'pOx* •pOy*)) 



The next seven functions stripe the shaft of the large arrow. 
First is a controlling function, then three functions to stripe 
the left side and three more to stripe the right. 

Function controlling striping of the shaft of the large arrow. 
Just calls STRIPE-BIG-ARROW-SHAFT-LEFT to stripe the left side 
and STRIPE-BIG-ARROW-SHAFT-RIGHT to stripe the right side, 
(defun stripe-big-arrow-shaft () 

(stripe-big-arrow-shaft-left) 

(stripe-big-arrow-shaft-right)) 

Function controlling striping of left side of big arrow's shaft. 

Iterates over the triangles that make up the shaft. Determines 

coordinates of the apex and bottom right point of each triangle. 

Calls DRAW-BIG-ARROW-SHAFT-STRIPES-LEFT to stripe each triangle. 

(defun stripe-big-arrow-shaft-left () 

:; Set up a counter for depth. Don't exceed maximum recursion 
;; level. 

(loop for shaft-depth from below •max-depth* 
:; Find current top edge and its fractions 
for top-edge = *top-edge« then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top-edge 4) 
;; Find coordinates of apex of triangle 
for apex-x = »p2x« then (- apex-x top-edge-2) 
for apex-y = •p2y* then (- apex-y top-edge-2) 
;; Find x-coord of bottom right vertex 
for right-x = (+ apex-x top-edge-4) 
;; Find y-coord of bottom edge of triangle 
for bottom-y = (- apex-y top-edge-4) 
;: Find the x-coord of the projection of the first 
;; stripe onto top edge 

for xoff = (- 'pOx* 'top-edge*) then (- xoff top-edge) 
;; Stripe each triangle 
do (draw-big-arrow-shaft-stripes-left 

top-edge-4 apex-x apex-y right-x bottora-y xoff))) 
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Stripes each triangle In left side of big arrow's shaft. 
Arguments are one-fourth current top edge, x- and y-coords 
of apex of triangle, x- and y-coords of bottom right vertex, 
and x-coord of projection of first stripe onto top edge. 
Determines coordinates of starting and ending points for 
each stripe. Finds number of lines in the stripe. Calls 
DRAW-BIG-ARROW-SHAFT-LINES-LEFT to draw the lines that 
make up each stripe, 
(defun draw-big-arrow-shaft-stripes-left 

(top-edge-4 apex-x apex-y right-x bottom-y xoff) 
(loop with half-distance = (// •stripe-distance* Z) 

;; Find x-coord of last stripe in triangle 

with last-x = (- apex-x top-edge-4) 

;; Find x-coord of top of each stripe, decrementing 

;; from the apex by HALF the horizontal distance 

;; between stripes. Stop at last stripe. 

for start-x from apex-x by half-distance above last-x 

:; Find y-coord of top of stripe 

for start-y downfrom apex-y by half-distance 

;; Find x-coord of endpoint of stripe 

for end-x downfrom right-x by *stripe-d1stance* 

;; Find number of lines in the stripe 

for nllnes = (compute-nlines (- xoff (- right-x end-x))) 

;: Draw a stripe 

do (draw-big-arrow-shaft- lines- left 

nlines start-x start-y end-x bottom-y last-x))) 

Draws the lines for a stripe on left side of big arrow's shaft. 
Arguments are number of lines in the stripe, coords of starting 
and ending points for first line, and x-coord of last stripe to 
be drawn, 
(defun draw-big-arrow-shaft-lines-left 

(nllnes start-x start-y end-x end-y last-x) 
;; Set up two counters -- we need to draw two lines at once 
(loop for 1 from 

for 12 from by 2 

;; Find x-coord of top of first line in stripe 
for first-x = (- start-x 1) 
;; Don't exceed number of lines in stripe 
while « 12 nllnes) 

;; Don't go past the end of the triangle 
while (< last-x first-x) 
;; Draw a line 

do (send »dest* ':show-11nes first-x (- start-y 1) 
(- end-x 12) end-y) 
Draw a second line. The two lines are a refinement 
to stagger the endpoints of the lines so the diagonal 
edge looks neat, 
(send »dest» ':show-lines first-x (- start-y 1 1) 
(- end-x 12 1) end-y))) 
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Function controlling striping of right side of big arrow's shaft. 
Iterates over the triangles that make up the shaft. Determines 
coordinates of the top point of each triangle. Calls 
DRAW-BIG-ARROW-SHAFT-STRIPES-RIGHT to stripe each triangle, 
(defun strlpe-blg-arrow-shaft-rlght () 

;; Set up a counter for depth. Don't exceed maximum recursion 
;; level. 

(loop for shaft-depth from below •max-depth* 
;; Find new top edge and Its fractions 
for top-edge = •top-edge* then (// top-edge 2) 
for top-edge-2 = (// top-edge 2) 
for top-edge-4 = (// top-edge 4) 
;; Find coords of top point of triangle 
for start-x = (+ •p2x* top-edge-4) 
for top-y = (- •p2y« •top-edge-4*) 
then (- top-y top-edge-2 top-edge-4) 
;; Find x-coord of projection of first stripe onto 
; ; top-edge 

for xoff = (- 'pOx* *top-edge*) then (- xoff top-edge) 
;; Stripe the triangle 
do (draw-big-arrow-shaft-stripes-right 

top-edge-2 top-edge-4 start-x top-y xoff))) 

Stripes each triangle in right side of big arrow's shaft. 
Arguments are one-half and one-fourth of current top edge, 
coords of top point of the triangle, and x-coord of projection 
of first stripe onto top edge. Determines coordinates of 
starting and ending points for each stripe. Finds number of 
lines that make up the stripe. Calls 
DRAW-BIG-ARROW-SHAFT-LIMES-RIGHT to draw a stripe, 
(defun draw-big-arrow-shaft-stripes-right 

(top-edge-2 top-edge-4 start-x top-y xoff) 
(loop with half-distance = (// 'stripe-distance* 2) 
;; Find y-coord of last stripe in triangle 
with last-y = (- top-y top-edge-2) 

;; Find y-coord of starting point of stripe. Don't go 
;; past the end of the triangle. 

for start-y from top-y by •stripe-distance^ above last-y 
;; Find coords of ending point of the stripe, decrementing 
;: by HALF the horizontal distance between stripes 
for end-x downfrom (+ start-x top-edge-4) by half-distance 
for end-y downfrom (- top-y top-edge-4) by half-distance 
;; Find number of lines that make up the stripe 
for nllnes = (compute-n lines (- xoff (- top-y start-y))) 
:; Draw a stripe 
do (draw-big-arrow-shaft- lines-right 

nlines start-x start-y end-x end-y last-y))) 
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Draws the lines for a stripe on right side of big arrow's shaft. 
Arguments are number of lines In the stripe, coordinates of starting 
and ending points for the first line, and y-coord of last stripe in 
the triangle, 
(defun draw-blg-arrow-shaft-llnes-rlght 

(nllnes start-x start-y end-x end-y last-y) 
;; Set up two counters -- we need to draw two lines at once 
(loop for 1 from 

for 12 from by 2 

;; Find y-coord of ending point of line 
for stop-y = (- end-y 1) 

;; Don't exceed number of lines in the stripe 
while « 12 nllnes) 

;; Don't go past the bottom of the triangle 
while (< last-y stop-y) 
; ; Draw a line 

do (send 'dest* ':show-lines start-x (- start-y 12) 
(- end-x 1) stop-y) 
Draw a second line. The two lines are a refinement 
to stagger the endpoints of the lines so the diagonal 
edge looks neat, 
(send 'dest* ':show-11nes start-x (- start-y 12 1) 
(- end-x 11) stop-y))) 



The remaining functions draw and stripe one of the small arrows 

Function controlling drawing of a small arrow. 

Calculates coordinates of the arrowhead and outlines it. Binds x-coord 
of the projection of the last stripe onto the top edge. Calculates 
the horizontal distance between stripes. When necessary, stripes the 
head and shaft of the arrow, 
(defun draw-arrow () 

;; Calculate coordinates of arrowhead vertexes 
(multiple-value-bind 

(*plx* 'ply* •p2x» •p2y» "pSx* »p5y* 'pCx* «p6y«) 

(compute-arrowhead-points) 
;; Outline the arrowhead 
(draw-outline) 
(when 'do-the-stripes* 

;; Bind x-coord of projection of last stripe onto top edge 
(let ((•x2* (- "pOx* 'top-edge* «top-edge«)) 
;; Calculate distance between stripes 
(•stripe-d" (compute-str1pe-d))) 
(stripe-arrowhead) ;Str1pe head 

(stripe-arrow-shaft))))) ;Str1pe shaft 

;;: Draws the outline of the head of a small arrow, 
(defun draw-outline () 

(send 'dest* ':show-1ines *p2x» »p2y» 'plx* 'ply* 
•pOx» 'pOy* 'pex* «p6y» *p5x» 'pSy*)) 
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;; Function controlling striping of the shaft of a snail arrow. 
;; Iterates over the descending triangles that make up the shaft. 
;; Calculates the coordinates of the top left and bottom right 
;; vertexes of each triangle. Finds the x-coord of the 
;; projection of the first stripe onto top edge. Calls 
;; DRAW-ARROW-SHAFT-STRIPES to stripe each triangle, 
(defun stripe-arrow-shaft () 

;; Set up a counter for depth. Don't exceed maximum 
;; recursion level. 

(loop for shaft-depth from 'depth* below *max-depth« 
;; Calculate fractions of new top edge 
for top-edge-2 = »top-edge-2« then (// top-edge-2 2) 
for top-edge-4 = {// top-edge-2 2) 
;; Find coords of top left point of triangle 
for left-x = •p2x» then (- left-x top-edge-4) 
for top-y = •p2y« then (- top-y top-edge-2 top-edge-4) 
;; Find coords of bottom right point of triangle 
for right-x = (* left-x top-edge-2) 
for bottom-y = (- top-y top-edge-2) 

;; Find x-coord of projection of first stripe onto top edge 
for xoff = (- 'pOx* 'top-edge') 
then (- xoff top-edge-2 top-edge-2) 
;: Stripe the triangle 
do (draw-arrow-shaft-stripes 

left-x top-y r1ght-x bottom-y xoff))) 

:; Stripes each triangle in the shaft of a small arrow. 
; ; Arguments are coordinates of the top left and bottom right 
;; points of the triangle, and the x-coord of the projection 
;; of the first stripe onto top edge. Calculates the y-coord 
;; of the starting point and the x-coord of the ending point 
;; of each stripe. Finds number of lines in the stripe. Calls 
;; DRAW-ARROW-SHAFT-LINES to draw the lines in the stripe, 
(defun draw-arrow-shaft-stripes 

(left-x top-y right-x bottom-y xoff) 
;; Find y-coord of starting point of stripe. Don't go 
;; below the bottom of the triangle. 

(loop for start-y from top-y by 'stripe-d* above bottora-y 
;; Find x-coord of ending point of the stripe 
for end-x downfron right-x by »stripe-d* 
;; Find number of lines in the stripe 
for nlines = (compute-nlines (- xoff (- right-x end-x))) 
; : Draw a stripe 
do (draw-arrow-shaft- lines 

nlines left-x start-y end-x bottom-y))) 
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; Draws the lines 1n a stripe In the shaft of a snail arrow. 
; Arguments are the number of lines In the stripe and the 
; coordinates of the starting and ending points of the first line, 
(defun draw-arrow-shaft-llnes 

(nllnes left-x start-y end-x bottom-y) 
;; Set up a counter. Don't exceed number of lines In the stripe, 
(loop for 1 from below nllnes 

;; Find x-coord of ending point of the line 
for last-x = (- end-x 1) 

:; Don't go past the left edge of the triangle 
while « left-x last-x) 
; ; Draw a line 

do (send *dest* ':show-11nes left-x (- start-y 1) 
last-x bottom-y))) 
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Appendix B 
Output Module for the Sample Program 



The program used as an example in this document draws the recursive arrow graphic on the 
document's cover. This appendix contains Lisp code that defines the flavors and methods that 
mediate between the program and the system output operations. Appendix A (page 133) 
contains the code that calculates coordinates for the endpoints of the lines that compose the 
figure. Appendix C (page 165) contains a reproduction of the LGP graphic the program 
produces. 

;;; -*- Mode: LISP; Package: (GRAPHICS GLOBAL 1000); Base: 10 -«- 
;;; Copyright (c) 1983 Symbolics, Inc. 



'I 

This file contains the output nodule for a program that 

reproduces the recursive arrow graphic printed on the covers 
of most Symbolics documents. The module allows the graphic 
to be produced on a Lisp Hachlne screen, a Laser Graphics 
Printer, or an LGP record file. For each of these devices, 
the module produces output by sending appropriate messages 
with the coordinates of the endpoints of line segments to 
be drawn. This module receives these coordinates from a 
separate calculation module. 

For screen output, the module creates its own windows. It 
defines a basic flavor of window that accepts point 
coordinates in the screen coordinate system, with origin 
at top left. It defines a more specialized window, built 
on the basic window, for use with a calculation module that 
uses LGP coordinates, with origin at bottom left. It 
allows a process to be associated with each window and 
lets users modify the characteristics of the figure. 

For LGP output, the module makes an instance of a flavor 
with the output stream as an Instance variable. Output is 
directed to either a hardcopy device or a record file. 

This module defines the top-level function, DO-ARROW, that 
is called to produce the graphic. This function pops up 
a choose-variable-values window to allow users to select the 
output device and the characteristics of the figure. The 
module defines conditions and handlers for attempts to give 
variables impermissible values. 
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This module determines the size of the figure and Its 
position within the page or window. It then calls the 
function DRAW-ARROW-GRAPHIC In the calculation module. 
It passes as arguments the length of the top edge of the 
figure and the coordinates of the top right point. The 
calculation module sends :SHOW-LINES messages to Instances 
of output flavors. The arguments to :SHOW-LINES are the 
coordinates of the endpolnts of lines to be drawn. The 
current Instance of the output flavor Is the value of the 
special variable 'DEST*. 
I# 



;;; Following are declarations for special variables 

(defvar *dest-str1ng» "Screen" 

"Destination of program output [Screen, LGP, or File]") 

(defvar 'output-file* nil 
"Pathname for LGP-record-file output") 

(defvar 'fm -proportion* 0.9 
"Proportion of smaller dimension to be filled by figure") 



;;; The following flavor and its methods are common to both 
; ; : screen and LGP output 

(defflavor arrow-parameter-mixin 

(width height top-edge right-x top-y) 

() 

(:gettable-1nstance-variables top-edge right-x top-y) 

( : required-methods :compute-width-and-he1ght) 

(:documentat1on :mixin 
"Provides parameters for size and position of figure. 
Instance variables hold width and height of page or window; 
length of top edge of figure; and coordinates of top right point 
of figure. Methods calculate size and position of figure by 
centering it within the page or window and making it fill no 
more than the specified proportion of the smaller dimension. 
The methods use a coordinate system with origin at bottom left; 
other mixlns must correct for this If output is going to a 
window. Other flavors must also provide a method for calculating 
width and height of the page or window. This flavor should be 
mixed into any instantiable flavor that produces output for the 
arrow graphic.")) 
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Method controlling calculation of size and position of figure. 
Sends messages to self to calculate width and height of page 
or window, length of top edge of figure, and coordinates of 
figure's top right point. These are separate methods so that 
other flavors can shadow them or add daemons. Another flavor 
must provide a method to compute width and height, because 
this Is specific to the output device, 
(defmethod (arrow-parameter-mlxln : compute-parameters) () 

; ; Another flavor must supply method for width and height 

(send self *:compute-w1dth-and-he1ght} 

;; Make a preliminary estimate of length of top edge 

(send self ':compute-top-edge) 

:; Adjust top edge to make It a multiple of 128 

(send self ':adJust-top-edge) 

;; Calculate coordinates of top right point of figure. 

;; We can't do this until we know how long top edge Is. 

(send self ' :compute-r1ght-x) 

(send self ' :compute-top-y)) 

Hakes a preliminary estimate of length of top edge. 
The top edge of the arrow Is 80 percent of the horizontal 
or vertical length of the whole figure. First finds the 
smaller of the length or width of the page or window. 
Multiplies this by the proportion of this dimension that 
Is to be filled by the figure. The result Is the 
horizontal or vertical length of the figure. Multiplies 
this by 0.8 to get the length of the top edge, 
(defmethod (arrow-parameter-mlxln :coinpute-top-edge} () 
(setq top-edge 

(fixr (» 0.8 »f111-proport1on» (min width height))))) 

Adjusts length of top edge so It Is a multiple of 128. 
There are 64 stripes In the head of the large arrow. The 
calculation module divides the length of top edge by two 
each time It goes down another recursion level. By making 
the original top edge a multiple of 128, we maximize 
continuity In striping between arrowheads and shafts and 
among the first several levels of recursion, 
(defmethod (arrow-parameter-mlxln :adjust-top-edge) () 
(setq top-edge 

;; Minimum length of top edge Is 128 
(If « top-edge 256) 128 

:; Otherwise set to next lower multiple of 128 
(• 128 (fix (// top-edge 128)))))) 

Calculates x-coordlnate of top right point of figure. 
Finds horizontal length of figure by dividing length of 
top edge by 0.8. Centers the figure horizontally within 
the page or window, 
(defmethod (arrow-parameter-mlxln :compute-r1ght-x) () 
(setq right-x 

(fixr (• 0.5 (+ width (// top-edge 0.8)))))) 
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Calculates y-coordlnate of top right point of figure. 
Assumes that the origin Is at bottom. Finds vertical 
length of figure by dividing length of top edge by 0.8. 
Centers the figure vertically within the page or window, 
(defmethod (arrow-parameter-nilxln :coinpute-top-y) {) 
(setq top-y 

(fixr (• 0.5 (+ height (// top-edge 0.8)))))) 



;;; Following are flavors and methods for screen output 

(def flavor basic-arrow-wlndow-mixin 

(do-stripes max-dep fill-prop) 
{) 

: inltable-instance-variables 

( :requ1red-flavors arrow-parameter-mlxin tv:w1ndow) 

(:default-1n1t-p11st 
ledges-from ':mouse :m1n1muin-w1dth 200 :ni1nimuin-he1ght 200 
:b11nker-p nil :expose-p t) 

(: documentation :mix1n 
"Provides for a basic window to display the arrow graphic. 
ARROW-PARAMETER-MIXIN is needed to position the figure within 
the window. Instance variables hold values for maximum 
recursion level, proportion of window to be filled, and 
whether or not to stripe the figure. This flavor assumes 
window coordinates, with origin at top left. It provides its 
own : COMPUTE-TOP- Y method to use that origin. It provides a 
method to find the width and height of the window, as 
ARROW- PARAMETER-HIXIN requires. This flavor has a :SHOW-LINES 
method to receive point coordinates from the calculation 
module and draw lines on the window. It provides a :HAIN-L0OP 
method so that the window can run in its own process and let 
the user modify the graphic. TV:LIST-M0USE-BUTT0NS-MIX1N Is 
needed to handle mouse clicks If this method Is used. This 
flavor provides standard :AFTER daemons for the window-system 
:INIT. :REFRESH, and :CHANGE-0F-SIZE-0R-HAR6INS messages. This 
flavor should be mixed In with ARROW-PARAMETER-MIXIN and 
TV:WINDOW for any window that produces the graphic. It 
should be Included before ARROW-PARAMETER-HIXIN so that the 
:COMPUTE-TOP-Y method shadows correctly.")) 
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Receives endpoint coordinates and draws lines on a window. 
Arguments are alternating x- and y-coord1nates of the end- 
points of lines to be drawn. If there are more than two pairs 
of coordinates, assumes that the endpoint of one line is the 
starting point of the next. Sends messages for separate methods 
to determine the actual coordinates. This Is so that other 
flavors can modify the coordinates. Draws a line by sending self 
a :DRAW-LINE message, and so assumes that TV:GRAPHICS-HIXIN is 
Included somewhere to provide this method, 
(defmethod (baslc-arrow-wlndow-mlxin :show-1ines) 
(x y &rest x-y-palrs) 
First determine the starting point of the line. On 
subsequent trips through the loop, the last endpoint 
becomes the next starting point, 
(loop for xO = (send self ':compute-x x) then xl 
for yO = (send self ':compute-y y) then yl' 
;; "Cddr" down the list created by making all but the 
;; first pair of coordinates an &rest argument 
for (xl yl) on x-y-pairs by #'cddr 
;; Determine the endpoint of the line 
do (setq xl (send self ':compute-x xl) 

yl (send self ':compute-y yl)) 
;; Draw the line 
(send self ':draw-11ne 

xO yO xl yl tv:alu-1or t))) 

; Determines the x-coordlnate of an endpoint of a line. 
; This Is a separate method so that other flavors can shadow 
; It or add daemons to manipulate the coordinate, 
(defmethod (baslc-arrow-wlndow-mixin :compute-x) (x) 
(fixr x)) 
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Determines the y-coordlnate of an endpoint of a line. 
Assumes that the argument already uses window coordinates, 
with origin at top left. This Is a separate method so that 
other flavors can shadow it or add daemons to manipulate 
the coordinate, 
(defmethod (baslc-arrow-wlndow-mlxin :corapute-y) (y) 
(fixr y)) 

Finds the inside width and height of the window. 
Sends self an :INSIDE-SIZE message, and so assumes that 
TV:MINIMUM-WINDOW Is included somewhere to provide this 
method, 
(defmethod (basic-arrow-window-mix In 

:compute-width-and-height) () 
(multiple-value (width height) 
(send self ':ins1de-size))) 

Calculates y-coordinate of top right point of figure. 
Finds vertical length of the figure by dividing the length 
of top edge by 0.8. Centers the figure vertically within 
the window. Gives the result in window coordinates, with 
origin at top left. This method shadows that in 
ARROW-PARAMETER-MIXIM . 
(defmethod (basic-arrow-window-ralxin -.compute-top-y) () 
(setq top-y 

(fixr (• 0.5 {- height (// top-edge 0.8)))))) 

Calculates size and position of figure after Initialization. 
Binds the global variable •fill-proportion* to the value of 
the corresponding Instance variable so that the figure win 
be drawn correctly If the value of •fill -proportion* has 
changed. 

(defmethod (basic-arrow-window-mixln :after :in1t) (Ignore) 
(let ((•fin-proportion* fin-prop)) 
(send self ':compute-parameters))) 

Calculates size and position of figure after window change. 
Binds the global variable •fin-proportion* to the value of 
the corresponding Instance variable so that the figure win 
be drawn correctly if the value of •fill-proportion* has 
changed, 
(defmethod (basic-arrow-window-mixln 

:after :change-of-size-or-margins) (&rest Ignore) 
(let ((•fin-proportion* fill-prop)) 
(send self ' :compute-parameters))) 
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;; Draws the figure when necessary after window Is refreshed. 
;; Binds the global variable 'dest* to self and the variables 
;; «do-the-str1pes« and •max-depth* to the corresponding Instance 
;; variables so the figure win be drawn correctly If the values 
;; of the global variables have changed, 
(defmethod (baslc-arrow-wlndow-mlxln :after :refresh) 
(&opt1onal type) 
;; Draw figure If not restored from a bit-save array ... 
(when (or (not tv:restored-b1ts-p) 

;; ... or size has changed 

(eq type ' :s1ze-changed) 
;; ... or new values for figure parameters, 
(eq type *:new-va1s)) 
;; If restored from a bit-save array, clear screen first 
(when tv:restored-b1ts-p 

(send self ' :clear-screen)) 
;; Bind global variables to self and Instance variables 
(let ((«dest» self) 

(•do-the-stripes« do-stripes) 
(*max-depth* max-dep)) 
;; Draw the figure 
(draw-arrow-graphic top-edge right-x top-y)))) 

Provides a mouse documentation line for the window. 
The only option Is to click right and pop up a 
choose-varlable-values window of options for changing 
the graphic on this window, 
(defmethod (basic-arrow-wlndow-mixin 

:who-l ine-documentation-string) ( ) 
"R: Choose-varlable-values options for changing figure on this window") 
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Command loop for window associated with a separate process. 
Consists of an error-restart-loop that handles restarts from 
errors and sys:abort. Walts for mouse Input. If a right 
click, pops up a choose-varlable-values window to change 
characteristics of the figure. On exit, sets instance variables 
to the new values and refreshes the window, then waits for another 
mouse click. Assumes blips are lists of the form provided 
by TV:LIST-HOUSE-BUTTONS-MIXIM. 
(defmethod (baslc-arrow-window-mixln :ma1n-1oop) () 

;; Run forever In a loop. Offer a restart handler If an error 
;; or sys:abort Is signalled. 

(error-restart-loop ((error sys:abort) "Arrow Window Top Level") 
;; Wait for input 
(let ((char (send self ':any-tyi))) 

;; Pop up window if input is a list ... 
(when (and (listp char) 

;; ... and a iiouse click ... 
(eq (first char) ' :mouse-button) 
;; ... and a single click on the right button, 
(eq (second char) #\mouse-r-l)) 
;; Bind global variables to instance-variable values 
(let (('do-the-stripes* do-stripes) 
(•max-depth* max-dep) 
(•fill-proportion* fill-prop)) 
;; Pop up a choose-variable-values window 
(tv:choose-vari able-values 

•((•do-the-str1pes» "Stripe the arrows?" :boolean) 
(•max-depth* "Number of recursion levels" cnumber) 
(•fill-proportion* 
"Fraction of window to be filled" inumber)) 
;; Nake the window wide to provide enough room for error 
;; messages. 
*: extra-width 20 

;: Call a function to check for errors when values change 
':funct1on 'check-item 
; ; Give the user a chance to abort 

':margin-choices '("Do It" ("Abort" (signal 'sys:abort))) 
': label 'Choose Options for Graphic") 
;; Set Instance variables to the new values 
(setq do-stripes *do-the-str1pes» 
max-dep •max-depth* 
fin-prop *fni-proport1on») 
;; Recompute size and position of the figure 
(send self ':compute-parameters) 

;; Send :REFRESH message with argument of ':new-vals to make 
;; sure the figure is redrawn if there is a bit-save array 
(send self ':refresh ':new-vals)))))) 
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(defflavor basic-arrow-window () 

(baslc-arrow-wlndow-mlxln 
arrow-par ameter-mlxin 
tv:any-ty1-mix1n 
tv:11st-inouse-buttons-m1x1n 
tv:process-iii1x1n 
tvtwindow) 
( :documentat1on icomblnatlon 
"Instantlablo flavor providing a basic window for output. 
Though this flavor Is Instantlablo. Its methods assume that 
point coordinates use the window coordinate system, with 
origin at top left. To work with the current calculation 
module it needs another mixln to convert LGP to screen 
coordinates. In the component flavors. BASIC-ARROW-WINDOW-HIXIN 
must come before ARROW-PARAMETER-MIXIN and TVrWINDOW for 
shadowing and daemons to work correctly. TV:PROCESS-MIXIM 
and TV:LIST-MOUSE-BUTTONS-MIXIM are not necessary unless the 
window is associated with a separate process and the :MAIN-LOOP 
method of BASIC-ARROW-WINDOW-MIXIN Is the command loop.")) 



(defflavor Igp-wlndow-mixin 
((scale-factor 2.5)) 
() 
( :requ1red-f lavors basic-arrow-window) 
(:documentat1on tmlxin 
"Converts LGP to screen coordinates and vice versa. 
When mixed in with BASIC-ARROW-WINDOW, this flavor allows 
window output with a calculation module that uses LGP 
coordinates. The Instance variable SCALE-FACTOR Is the 
ratio of LGP to screen pixel density. The methods take 
the height and width of the window In screen pixels and 
calculate the length of the top edge and the coordinates 
of the top right point of the figure In LGP pixels. In 
drawing lines on the window, the methods convert LGP to 
window coordinates. These methods shadow those In 
ARROW-PARAMETER-MIXIN and BASIC-ARROW-WINDOW-MIXIN.")) 



; Converts x-coord of line endpoint from LGP to screen pixels. 
; Corrects for higher density of LGP pixels. This method shadows 
that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-wlndow-mlxin :compute-x) (x) 
(fixr (// x scale-factor))) 

Converts y-coord of line endpoint from LGP to screen pixels. 
Corrects for higher density of LGP pixels and for screen origin 
at top left. This method shadows that of BASIC-ARROW-WINDOW-MIXIN. 
(defmethod (Igp-window-mlxin :compute-y) (y) 
(fixr (- height (// y scale-factor)))) 
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;;; Calculates top edge in LGP pixels from screen proportions. 
;;; Multiplies length of smaller dimension, in screen pixels, by 
;;; proportion of this dimension to be filled by the figure. 
;;; Multiplies this by 0.8 to find top edge In screen pixels. 
;;; Corrects for higher density of LGP pixels. This method 
;;; shadows that of ARROW- PARAMETER-MIXIN. 
(defmethod (Igp-window-mixin : compute-top-edge) () 
(setq top-edge 

(fixr (» scale-factor 0.8 •fill-proportion* 
(min width height))))) 

;;; Calculates x-coord of top right point in LGP pixels. 
;;; Finds horizontal length of figure In screen pixels by 
;;; dividing top edge by 0.8. Centers figure horizontally 
;;; In window, correcting for higher density of LGP pixels. 
:;; This method shadows that of ARROW- PARAMETER-MIXIN. 
(defmethod (Igp-window-mixin :compute-r1ght-x) () 
(setq right-x 

(fixr (* 0.5 (+ (* width scale-factor) 
(// top-edge 0.8)))))) 

;;; Calculates y-coord of top right point in LGP pixels. 
;;; Finds vertical length of figure in screen pixels by 
;;; dividing top edge by 0.8. Centers figure vertically 
;;; in window, correcting for higher density of LGP pixels. 
;:: This method shadows those of ARROW- PARAMETER-MIXIN and 
;;; BASIC-ARROW-WINDOW-MIXIM. 
(defmethod (Igp-window-mixin :compute-top-y) () 
(setq top-y 

(fixr (• 0.5 (* (• height scale-factor) 
(// top-edge 0.8)))))) 



(defflavor arrow-window () 

( Igp-window-mixin basic-arrow-window) 
(:documentation :combinat1on 
•Instantiable flavor for window output from LGP coordinates. 
This flavor has all the features of BASIC-ARROW-WINDOW but 
assumes that the calculation module uses LGP coordinates. This 
is the flavor to Instantiate for window output using the 
current calculation module.")) 
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;;; The following flavor and methods are for LGP output 

(defflavor 1gp-pixe1-m1x1n 
(output-stream) 

() 

: 1n1tab1e-1nstance-var1ab1es 

( :requ1red-flavors arrow-parameter-mixin) 

(:documentat1on :m1x1n 
"Provides methods for arrow graphic output on an LGP stream. 
ARROW-PARAMETER-MIXIN is required to calculate the size of the 
figure and position it in the center of the page. This flavor 
has a method to calculate the width and height of the page, as 
ARROW-PARAMETER-MIXIN requires. It has a :SHOW-LINES method to 
receive point coordinates from the calculation module and draw 
lines on the output stream. The method assumes that coordinates 
are in LGP pixels. The method also assumes that flavor 
LGP:BASIC-LGP-STREAM is Included In output stream to provide 
:SEND-COMMAND and :SENO-COORDINATES messages. This flavor 
should be mixed, along with ARROW-PARAMETER-MIXIN, Into an 
instantlable flavor for LGP output. When that flavor is 
instantiated, the Instance variable output-stream should be 
initialized.")) 



Receives endpoint coordinates and draws lines on LGP stream. 
Arguments are alternating x- and y-coordinates of endpoints of 
lines to be drawn. If there are more than two pairs of 
coordinates, assumes that the endpoint of one line is the 
starting point of the next. Draws a line by sending output 
stream :SEND-COMMAND messages for LGP commands and 
:SENO-COORDINATE messages for LGP coordinates. Assumes that 
flavor LGP:BASIC-LGP-STREAM is included In output stream to 
provide these methods, 
(defmethod (Igp-pixel-mixln :show-11nes) 
(xO yO Arest x-y-pairs) 
;; Send conunand and coordinates to start drawing lines 
(send self 'isend-command-and-coordinates #/m xO yO) 
;; 'Cddr" down the list created by making all but the first 
;; pair of coordinates an &rest argument 
(loop for (X y) on x-y-paIrs by #'cddr 

;; Send command and coordinates to draw a line 

do (send self *:send-command-and-coord1nates #/v x y))) 

Sends line-drawing commands to LGP output stream. 

:SEND-COMMAND transmits an LGP command. :SEND-COORDINATES 

transmits coordinates of an endpoint of a line to be drawn. 

Assumes that LGP:BASIC-LGP-STREAN is included In output stream 

to provide these methods, 
(defmethod (Igp-pixel-mixln :send-command-and-coord1nates) (cmd x y) 
(send output-stream ' :send-command cmd) 
(send output-stream ':send-coordinates (fixr x) (fixr y))) 
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Finds width and height of a page for LGP output. 
This flavor Is required by ARROW-PARAMETER-NIXIN . Finds the 
values of two instance variables of LGP:BASIC-LGP-STREAH: 
SI: PAGE-WIDTH and SI: PAGE-HEIGHT. Assumes that 
LGP:BASIC-LGP-STREAM is Included In output stream to provide 
these Instance variables, 
(defmethod (Igp-plxel-mixin :conpute-w1dth-and-he1ght) () 
(setq width (symeval-in-instance output-stream 'si:page-w1dth) 

height (symeval-ln-lnstance output-stream 's1:page-he1ght))) 



(defflavor 1gp-pixe1-stream () 

(Igp-plxel-raixin arrow-parameter-mlxin) 
(idocumentation :combinat1on 
'Instantiable flavor for arrow output on LGP stream. 
Assumes that the calculation module uses LGP coordinates. 
When this flavor is instantiated, the LGP-PIXEL-HIXIN 
Instance variable OUTPUT-STREAM should be initialized. 
The output stream can be directed to an LGP or a file, 
but it must include flavor LGP:BASIC-LGP-STREAM for 
output to work correctly.')) 



;;; Following are condition flavors for bad variable values 

(defflavor bad-arrow-variable () (error) 
(idocumentation 
■Noninstantlable class of bad-variable conditions. 
The user might set some variables to impermissible values. 
These conditions are to permit checking for bad values 
beyond the system's error checking. Instantiable condition 
flavors for specific variables should be built on this 
flavor.")) 



(defflavor bad-arrow-depth () (bad-arrow-variable) 
(:documentation 
"Proceedable condition: bad value for «HAX-DEPTH*. 
An instantiable condition flavor for impermissible values 
of 'MAX-DEPTH*, the number of recursion levels in the 
figure.")) 

;;; Prints string on stream to report bad 'MAX-DEPTH* value 
(defmethod (bad-arrow-depth rreport) (stream) 
(format stream "No. of levels was not a ~ 
nonnegative fixnum.")) 
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;;; Proceed type method for supplying new value of *MAX-DEPTH* 
(definethod (bad-arrow-depth :case :proceed :new-depth) 
(&opt1ona1 (dep (prompt-and-read 
' : number 

"Supply new value for ~ 
no. of recursion levels: "))) 
"Supply a new value for number of recursion levels." 
(values ':new-depth dep)) 



(defflavor bad-arrow-flll-proportlon () (bad-arrow-varlable) 
( :documentat1on 
"Proceedable condition: bad value for »FILL-PROPORTIOM». 
An Instantlable condition flavor for Impermissible values of 
•FILL- PROPORTION*, the fraction of the smaller dimension of 
the page or window that the figure Is to fill.")) 

;;: Prints string on stream to report bad *FILL-PROPORTION« value, 
(defmethod (bad-arrow-flll-proportlon :report) (stream) 
(format stream "Proportion was not a fraction between ~ 
and 1.")) 

;;; Proceed type method for new value of •FILL-PROPORTION* 
(defmethod (bad-arrow-flll-proportlon :case :proceed 

: new-proportion) 
(&opt1onal (prop (prompt-and-read 
': number 

"Supply new fraction of bounds ~ 
be filled: "))) 
"Supply a new fraction of page or window to be filled." 
(values ': new-proportion prop)} 
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Top-level function 

Top-level function to call to produce arrow graphic. 
Pops up a choose-variable-values window to let user specify 
output destination, number of recursion levels, proportion 
of smaller dimension of page or window to be filled, and 
whether or not to stripe figure. If screen output, makes a 
window. If LGP output, makes an LGP stream and calls 
ORAW-ARROW-GRAPHIC to draw the figure, 
(defun do-arrow () 

;; Pop up a choose-variable-values window 
(tv:choose-var1able-values 

•((•do-the-stripes* "Stripe the arrows?" :boolean) 
(«max-depth« "Number of recursion levels" :number) 
(•fill-proportion* 

"Fraction of page or window to be filled" :number) 
(•dest-string* "Output destination" 

:choose ("Screen" "LGP" "File")) 
(•output-file* "Pathname for file output" :pathnane)) 
;; Make window wide enough to accommodate long pathnames 
; ; and error messages 
♦: extra-width 20. 

;; Call this function when a value is changed 
':function 'check-item 
; ; Give user a chance to abort 

•:marg1n-choices '("Do It" ("Abort" (signal 'systabort))) 
': label "Choose Options for Graphic") 
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;; If figure 1s Infinitely small, just return nil 
(cond ((= •fill-proportion* 0) nil) 

; ; If screen output, make a window 
((equal •dest-string* "Screen") 
(tv:iRake-w1ndow 'arrow-window 

;; Initialize instance variables to 
; ; values set by the user 
':do-str1pes 'do-the-strlpes* 
':niax-dep *niax-depth* 
•:fill-prop •fill-proportion* 
;; Specify top-level function for the 
;; process associated with the window 
':process '(window-loop))) 
;; If LGP or file output, use an appropriate stream 
(t (wlth-open-stream 
(stream 

;; This function returns a stream suitable for 

; ; LGP output 

(si :make-hardcopy-stream 

:; Argument is the output device. For LGP, 
;; use the default hardcopy device, 
(if (equal 'dest-string* "Igp") 
si :'defau1t-hardcopy-dev1ce« 
:; For file output, use the correct format 
;; for the hardcopy device and direct 
;; output to the file specified by the user 
(lgp:get-lgp-record-file-hardcopy-dev1ce 
•output-file*)))) 
;; Hake an instance of our LGP output flavor 
(let ((•dest^ 

(make-instance 'Igp-pixel-stream 

;; Initialize instance 
;; variable to output stream 
':output-stream stream))) 
;; Position the figure on the page 
(send «dest* ':compute-paraRieters) 
;; Draw the figure, using instance-variable values 
; ; as arguments 

(draw-arrow-graphic (send 'dest* ':top-edge) 
(send *dest* ':right-x) 
(send »dest* 'itop-y))))))) 



Top-level function for process associated with arrow window. 
The function is called when the window 1s created. Argument is 
the window. The function sends the window a :KAIN-LOOP message. 
This method should be the actual command loop for the process, 
(defun window-loop (window) 
(send window ':main-1oop)) 
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Called when a value changes In choose-var1ab1e-va1ues window. 
Arguments are the window, the variable, and Its old and new values. 
Binds handlers for conditions for Impermissible values. If new 
value Is OK, sets variable to the new value, refreshes window, and 
returns t. If value Is not OK, signals the appropriate condition. 
When SIGNAL returns, presumably with a new variable value, checks 
the new value In the same way It checks a new value that comes 
from the window, 
(defun check-item (cw-wlndow var old-val new-val) 

We don't use the old value. To avoid a compiler complaint, 
just evaluate It and Ignore It. We could also use IGNORE 
Instead of OLD-VAL In the argllst, but then the argllst 
would be less meaningful, 
old-val 

;; Bind handlers for the conditions we might signal 
(condition-bind ((bad-arrow-depth 'bad-arrow-var-handler) 
(bad-arrow-fill-proportlon 
'bad-arrow-var-handler)) 
(when (eq var '»max-depth*) 

;; •MAX-DEPTH* must be nonnegatlve fixnura 
(loop until (and (fixp new-val) (Jt new-val 0)) 

If It's not, bind QUERY-IO to the window and 
signal a condition. SIGNAL should return 
two values, the proceed type and the new 
value from the proceed method. Ignore the 
proceed type and set NEW-VAL to the new 
value, 
do (let ((query-lo cw-wlndow)) 

(multiple-value (nil new-val) 
(signal 'bad-arrow-depth))))) 
(when (eq var ••fin-proportion*) 

;; •FILL-PROPORTION* must be between and 1 
(loop until (and (^ new-val 0) (s new-val 1)) 

If it's not, bind QUERY-IO to the window and 
signal a condition. SIGNAL should return 
two values, the proceed type and the new 
value from the proceed method. Ignore the 
proceed type and set NEW-VAL to the new 
value, 
do (let ((query-lo cw-window)) 

(multiple-value (nil new-val) 

(signal 'bad-arrow-fill-proportion))))) 
;; Variable value Is now OK. Set variable to the new value. 
;; Note that we DO want to evaluate VAR. 
(set var new-val) 
; ; Refresh the window 
(send cw-wlndow 'rrefresh) 
; ; Return t 
t)) 
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Handler for bad-var1ab1e-va1ue conditions 

Handler for bad value of «HAX-DEPTH» or »FILL-PROPORTION*. 
Argument Is the condition object created by SIGNAL. Uses QUERY-IO 
stream to report condition. Sends the condition object a :PROCEE0 
message and passes back the values It returns, 
(defun bad-arrow-var-handler (cond-obj &aux bl) 

;; Find out whether this object has the right proceed type. 

;; If not, return nil. 

(if (send cond-obj ' :proceed-type-p 

(cond ((typep cond-obj 'bad-arrow-depth) *:new-depth) 
((typep cond-obj 'bad-arrow-flll-proportlon) 
' :new-proport1on))) 
;; Enclose the handling operation in an UNWIND- PROTECT so that 
;: if we use a blinker we are sure to turn it off 
(unwind-protect 
(progn 

;; Use a blinker 1f the QUERY-IO stream Is a window 
(setq bl (if (typep query-io 'tv:sheet) 

;; If a cursor-following blinker exists, use it 
(or (tv:sheet-fol1ow1ng-b11nker query-io) 
;; Otherwise, make a new blinker 
(tv:make-b11nker query-io 

'tv:rectangu1ar-b1 Inker 
':fonow-p t)))) 
: ; If a blinker, make it blink 
(if bl (send bl ' :set-v1s1b111ty ':bl1nk)) 
; ; Alert the user 
(tv:beep) 

;; Send a report, presumably describing the condition 
(send cond-obj 'rreport query-io) 

;; Send object a : PROCEED message and return the values 
; ; that the method returns 
(send cond-obj *:proceed 

(cond ((typep cond-obj 'bad-arrow-depth) *:new-depth) 
((typep cond-obj 'bad-arrow-flll-proportlon) 
' : new-proportion ) ) ) ) 
;; If a blinker, turn it off 
(If bl (send bl 'tset-vlsibllity nil))))) 



This macro expression causes combined methods to be compiled at 
compile time and data structures to be generated at load time. 
Otherwise, these things happen at run time, when the first 
instance of a flavor is made, 
(compile-flavor-methods arrow-window Igp-plxel-strean 

bad-arrow-depth bad-arrow-flll-proportlon) 
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Appendix C 
Graphic Output of the Sampie Program 



The program used as an example in this document draws the recursive arrow graphic on the 
document's cover. This appendix contains a reproduction of the LGP graphic the program 
produces. Appendix A (page 133) contains Lisp code that calculates coordinates for the 
endpoints of the lines that compose the figure. Appendix B (page 147) contains the code that 
defines the flavors and methods that mediate between the program and the system output 
operations. 
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c-N (Stepper command) 86 

c-P (Debugger command) 75 

c-R (Debugger command) 75 

c-R (Reverse Search) 51 

c-s (Incremental Search) 50 

c-sh-A (Quick Arglist) 36 

c-sh-c (Compile Region) 64 

c-sh-D (Brief Documentation) 32, 35 

c-sh-E (Evaluate Region) 68 

c-sh-H (Macro Expand Expression) 94 

c-sh-v (Describe Variable At Point) 32 

e-sPACE (Set Pop Mark) 52 

c-u (Stepper command) 88 

c-x ( (Start Kbd Macro) 56 

c-x (Stepper command) 88 

c-x ) (End Kbd Macro) 56 

c-x 1 (One Window) 57 

c-x 2 (Two Windows) 57 

c-x 3 (View Two Windows) 57 

c-x 4 (Modified Two Windows) 57 

c-x ; (Set Comment Column) 21 

c-x B (Select Buffer) 52 

c-x c-0 (Display Directory) 37 

c-x c-F (Find File) 7 

c-x c-x (Swap Point And Mark) 52 

c-x D (tr Dired) 38 

c-x E (Call Last Kbd Macro) 56 

c-x F (Set Fill Column) 10 

e-x G (Open Get Register) 55 

c-x H (Mark Whole) 56 

c-x J (Jump To Saved Position) 52 

c-x (Other Window) 57 

c-x s (Save Position) 52 

c-x x (Put Register) 55 

c-Y(Yank) 54 
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c-z (Quit) 74 

Call Last Kbd Macro (c-x e) 56 

Callers 36 

:case method combination 122 

:change-of-size-or-margins, Method for tT:slieet 109 

Changed code 49 

choose-variable-values, Function (in package tv:) 114, 

121 
Choose-variable- values window 114, 119 
Comments 19 
Compile Buffer (m-x) 64 
Compile Changed Definitions (m-x) 64 
Compile Changed Definitions Of Buffer (m-sh-c) 64 
Compile File (m-x) 65 
Compile Region (c-sh-c) 64 
compile-file. Function (in package compiler:) 65 
compile-file-load. Function (in package compiler:) 66 
compile-flavor-methods, Macro 128 
Compiled functions 61 
Compiler Warnings (m-x) 73 
Compiler warnings 57, 63, 71 
compiler:compile-file. Function 65 
compiler:compile-me-Ioad, Function 66 
Compiling code 61, 62 

COMPLETE 6 

Completion 6 
[Cond after] 87 
[Cond before] 87 
[Cond break after] 87, 91 
[Cond break before] 87,91 
:cond, Option to trace 87 
condition. Flavor 122 
condition-bind. Macro 123 
[Conditional] 87 
Conditions 121 
Copying buffers 55 
Copying files 55 
Creating files 7 

:daemon method combination 103, 106, lOS, 109, 1 10, 1 1 1 
Daemon methods 108, 109 
dbg. Function 90 
Debugger 71, 73, 89 
Debugger commands 

c-A 75 

c-E 75 

c-HELP 74 

c-L 75 

c-m-R 75 

c-m-» 73, 75 

c-H 75 

c-P 75 

c-R 75 

m-B 75 

m-L 75 
Debugging 71 



sdefault-init-pHst, Option to defnavor 106 
defconst Macro 62 
defflavor. Macro 103, 106 
defflavor Options 

:default-init-plist 106 

:documentation 129 

;gettable-in5tance-variable8 103 

:initable-instance- variables 1 1 2. 1 1 5 

trequired-flavors 106 

trequired-methods 103 
def system. Macro 51 
defvar. Macro 13, 62 
def window-resource. Macro 115 
Deinstall Macro (m-x) 56 
Describe Flavor (m-x) 129 
describe. Function 28, 30, 94 
Describe Variable At Point (c-ih-v) 32 
describe-flavor. Function 129 
Directories, File 37 
Dired (m-x) 38 
Disassemble (m-x) 97 
disassemble. Function 94, 97 
Display Debugger 73 
Display Directory (c-x c-D) 37 
documentation. Function 32, 36 
•documentation. Option to defflavor 129 
Documentation strings 32, 34 
Down Comment Line (m-N) 20 
tdraw-line. Method for tv:grapMcs-mixin 11, 106 

:edges-from, Init Option to tvsminimum-window 106 

[Edit] 7,74 

Edit Callers (m-x) 37 

Edit Changed Definitions (m-x) 49 

Edit Changed Definitions Of Buffer (m-x) 49 

Edit Combined Methods (m-x) 131 

Edit Compiler Warnings (m-x) 73 

Edit Definition (m-.) 33,128,129 

Edit Methods (m-x) 57, 1 3 1 

[Edit Screen] 58,121 

Electric Shift Lock Mode (m-x) 10 

END 6 

End Kbd Macro (c-x )) 56 

:entrjr. Option to trace 87 

:entrycond, Option to trace 87 

:entryprint. Option to trace 87 

[Error] 87,90 

error. Flavor 122 

terror. Option to trace 87,91 

error-restart-loop, Macro 119 

Evaluate And Replace Into Buffer (m-x) 68 

Evaluate Buffer (m-x) 68 

Evaluate Changed Definitions (m-x) 68 

Evaluate Changed Definitions Of Buffer (m-sh-E) 68 

Evaluate Into Buffer (ra-x) 68 

Evaluate Minibuffer (m-ESCAPE) 68 
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Evaluate Region (c-jh-E) 68 

Evaluating code 61, 66, 86 

[Exit] 94 

rexit, Option to trace 87 

texstbreak. Option to trace 87, 91 

:exitcond. Option to trace 87 

texitprint, Option to trace 87 

Expanding macros 91 

lexpose-p, Init Option to tviminimum-window 106 

Files 

Attribute lists 7 

Copying 55 

Creating 7 

Directories 37 

Init 9, 56 
Fill Long Comment (m-x) 20 
Find File (c-X c-F) 7 
Find Unbalanced Parentheses (m-x) 22 
flavor-allowed-init-key words; Function (in package si:} 

131 
Flavors 

condition 122 

error 122 

Igp:basic-lgp-stream 112, 113 

si:TaniIla-flavor 129 

$ys:abort 119 

tv:any-tyi-mixin 118 

tTtgraphics-mixin 106 

tT:Iist-mouse-battons-mixin 118 

tTcminimum- window 107 

tT:proce5S-mixin 118 

tv:slieet 127 

tT:window 102, 105, 106, 107 
Function Apropos (m-x) 34 
:f unction. Option to tv:choose-varlable-Ta!ues 121 
Functions 33 

apropos 31 

arglist 36 

breakon 90 

Compiled 61 

conipiIer:compiIe-fiIe 65 

coiDpiler:compile-nie-!oad 66 

dbg 90 

describe 28, 30, 94 

describe-flavor 129 

disassemble 94, 97 

documentation 32, 36 

get-handler-for 131 

inspect 97 

Interpreted 61 

listarray 30 

load 66 

make-system 71 

mexp 94 

pkg-goto 17 



plist 32 

prompt-and-read 126 

si:flaTor-alIowed-init-key words 1 3 1 

si :m3ke-hardcopy -stream 116 

signal 102, 123, 126 

Step 89 

tv:choose-Tariable- values 114, 121 

tv:make-blinker 127 

tT:make-window 102. 1 12, 1 IS. 1 18 

tT:sheet-followiug-blinker 127 

typep 129 

unbreakon 90 

what-files-call 32 

wbere-is 31 

who-calls 32 

Generic operations 102 
get-handler-for, function 131 
tgettable-instance-variables. Option to def flavor 103 
graphics-mixin. Flavor (in package tv:) 106 

HELP 5, 6, 56, 86 

Incremental Search (e-s) 50 

Indent For Comment (c- ; or m- ;) 20 

Indent For Lisp (TAB or c-m- tab) 21 

Indent New Comment Line (m-LiNE) 20 

Indent New Line (line) 21 

Indent Region (c-m-\) 21 

Indent Sexp(c-m-o) 21 

Init files 9, 56 

Init keywords (for flavors) 131 

:init. Method for tvzsheet 109 

Init Options 
:blinker-p to tvtminimum-window 106 
:edges-from to tv:minimum-window 106 
:expose-p to tv:minimum-window 106 
:minimum-heigbt to tT:miuimam-window 106 
:minimum-wldth to tT:minimum-window 106 
;process to tv:process-mixin 1 1 8 

anitable-instance-variableSk Option to def flavor 1 12, 
115 

Insert Buffer (m-x) 56 

Insert File (m-x) 56 

:inside-size, Method for tT:minimum-window 107 

[Inspect] 97 

inspect Function 97 

Inspector 94, 128 

Install Macro (m-x) 56 

Install Mouse Macro (m-x) 56 

Instance variables 103,112,115 

Interpreted functions 61 

Jump To Saved Position (c-x j) 52 
Keyboard macros 56 
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Kill Comment (e-m- ;) 
Kill Sexp (c-m-K) 54 
Killing text S2 



20 



Igptbasic-lgp-stream, Flavor 1 12, 1 13 
Igp:basic-lgp-stream Methods 

:send-cominand 113 

:send-coordinate8 113 

LINE (Indent New Line) 21 
Lisp input editing 68 
Lisp input editor commands 

c-c 69 

m-C 69 
Lisp Mode (m-x) 10 
List Callers (m-x) 31,37 
List Changed Definitions (m-x) 49 
List Changed Definitions Of Buffer (m-x) 49 
List Combined Methods (ffl-x) 131 
List Matching Lines (m-x) 50 
List Matching Symbols (ra-x) 32 
List Methods (m-x) 130 

list-mouse-buttons-mixiii. Flavor (in package tv:) 118 
listarray. Function 30 
Load Compiler Warnings (m-x) 73 
Load File (m-x) 66 
load. Function 66 
Long Documentation (m-sh-D) 32, 36 

m-x (Query Replace) 51 

m-. (Edit Definition) 33, 128, 129 

m- ; (Indent For Comment) 20 

m-B (Debugger command) 75 

m-C (Lisp input editor command) 69 

m- ESCAPE (Evaluate Minibuffer) 68 

m-L (Debugger command) 75 

m-LiNE (Indent New Comment Line) 20 

m-H (Down Comment Line) 20 

m-p (Up Comment Line) 20 

m-ih-C (Compile Changed Definitions Of Buffer) 64 

m-sh-D (Long Documentation) 32, 36 

m-sh-E (Evaluate Changed Definitions Of Buffer) 68 

m-SPACE (Push Pop Point Explicit) 52 

m-w (Save Region) 54 

m-Y (Yank Pop) 54 

Macro Expand Expression (c-$h-M) 94 

Macro Expand Expression All (m-x) 94 

Macros 

compile-flavor-methods 128 

condition-bind 123 

defconst 62 

defHavor 103,106 

def system 51 

defvar 13,62 

def w indo w-resource 1 1 5 

error-restart-loop 119 

Expanding 9 1 



Keyboard 56 

with-open-stream 116 
make-blinker, Function (in package tv:) 127 
make-hardcopy -stream, Function (in package si:) 116 
make-system. Function 71 
make-system Options 

:batcb 71 
make-window. Function (in package tv:) 102, 112, 115, 

118 
Mark Definition (c-m-H) 54 
Mark Whole (c-x h) 56 
Menu items 

[ARGPDL] 86 

[Attributes] 128 

[Break after] 86 

[Break before] 86 

[Cond after] 86 

[Cond before] 86 

[Cond break after] 86,91 

[Cond break before] 86,91 

[Conditional] 86 

[Edit Screen] 58, 121 

[Edit] 7,74 

[Error] 86,90 

[Exit] 94 

[Inspect] 97 

[Modify] 95 

[Print after] 86 

[Print before] 86 

[Print] 86 

[Retry] 74 

[Return] 94,95 

[Split Screen] 58, 121 

[Step] 86,89 

[Trace] 85,89 

[Untrace] 86 

[Wherein] 86 
Method combination 

:case 122 

:daemon 103, 106, 108, 109, 1 10, 1 11 
Methods 129 

:any-tyi for tT:flny-tyi-mixin 119 

:c]iange-of-size-or-margin$ for tT:sheet 109 

Daemon 108, 109 

:draw-Iine for tv:graphics-mixiB 11, 106 

:init for tv:$heet 109 

;inside-size for tv:minimum-window 107 

:operation-handled-p for sitTauilla-naTor 1 3 1 

Primary 103,108,110 

zproceed 122, 123, 126 

:refresh for tv:sbeet 109, 120 

:report 122, 126 

•send-command for lgp:basic-lgp-stream 113 

:5end-coordinates for lgp:basic-Igp-stream 1 1 3 

:which-operatlons for siivanilla-navor 131 

:wbo-line-documentation-string 119 
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mexp, Function 94 

Minibuffer 6 

•minimum-lieight Init Option to tvtminimum-windoir 

106 
cmiBimum-widtli, Init Option to tTzminimum-irindow 106 
minimuiii-window. Flavor (in package tv:) 107 
Modes 9 

Modified Two Windows (c-x 4) 57 
[Modify] 95 
Modularity 103 
Mouse clicks 118 
Mouse documentation string 119 
Move To Previous Point (c-m-SPACE) 52 
Moving text 5 1 
Multiple 

Buffers 57 

Windows 57 
Multiple Edit Callers (m-x) 37 
Multiple List Callers (m-x) 37 
multiple-value. Special Form 107 



Name Last Kbd Macro (m-x) 
:nil. Option to trace 87 



56 



Objects 28 

One Window (c-x 1) 57 

Open Get Register (c-x G) 55 

:operatioii-handled-n Method for si: vanilla-flavor 131 

Options 

:arg to trace 87 

;argpdl to trace 87 

thatch to make-system 71 

:both to trace 87 

:break to trace 87, 91 

:coiid to trace 87 

:defaalt-iiiit-plist to def flavor 106 

:documeDtation to def flavor 129 

:eiitry to trace 87 

:eDtrycond to trace 87 

:entryprint to trace 87 

:error to trace 87,91 

:exit to trace 87 

:exit break to trace 87, 91 

texitcond to trace 87 

:exitprint to trace 87 

:f unction to tv:choose-variahle-valaes 121 

:gettable-instance-variahles to defflavor 103 

nuitable-instance-variahles to defflavor 112, US 

:nil to trace 87 

:print to trace 87 

:required-fIavor« to defflavor 106 

:reqaired-methods to defflavor 103 

:step to trace 87, 89 

lvalue to trace 87 

: wherein to trace 87 
Other Window (c-x o) 57 



Packages 7,8,17,31,36 

Parentheses. Balancing 21 

Pathnames 37 

pkg-goto, Function 17 

plist Function 32 

Primary methods 103, 108, 1 10 

[Print] 87 

[Print after] 87 

[Print before] 87 

Print Modifications (m-x) 50 

:print Option to trace 87 

rproceed, Method 122, 123, 126 

Proceed types 74, 122 

Proceeding 122 

:process, Init Option to tv:process-mixin 118 

process-mixin, Flavor (in package tv:) 118 

Processes 118,119 

prompt-and-read. Function 126 

Push Pop Point Explicit (ib-space) 52 

Put Register (c-x x) 55 

Query Replace (m-x) 5 1 
query-io. Variable 126, 127 
Quick Arglist (c-ih-A) 36 
Quit (c-Z) 74 

:refresh. Method for tv:sheet 109, 120 

Registers 55 

Reparse Attribute List (m-x) 9 

Replace (c-x) 51 

Replacing 50 

:report Method 122, 126 

:required-navors. Option to defflavor 106 

:re4aired-methods; Option to defflavor 103 

Resources 115 

Restart handlers 74 

RESUME 68, 89 

[Retry] 74 

RETURN 6 

[Return] 94,95 
Reverse Search (c -r) 51 

Save Position (c-x s) 52 

Save Region (m-u) 54 

Scroll Other Window (c-m-v) 57 

Searching 50 

Select All Buffers As Tag Table (n-x) 51 

Select Buffer (c-x b) 52 

SELECT E 7 
SELECT I 97 

Select Previous Buffer (c-m-L) 52 

Select System As Tag Table (m-x) 5 1 

:send-commaDd, Method for lgp:basic-Igp-stream 113 

:send-coordinates, Method for Igp:basic-lgp-stream 1 1 3 

Set Backspace (m-x) 9 
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Set Base (m-x) 9 

Set Comment Column (c-x ;) 21 

Set Fill Column (c-X F) 10 

Set Fonts (m-x) 9 

Set Key (m-x) 56 

Set Lowercase (m-x) 9 

Set NofiU (m-x) 9 

Set Package (m-x) 9 

Set Patch File (m-x) 9 

Set Pop Mark (c-space) 52 

Set Tab Width (m-x) 9 

Set Vsp (m-x) 9 

sheet, Flavor (in package tv:) 127 

sheet-foUowing-blinker, Function (in package tv:) 

si:fIaTor-alIoired-iiiit-key words, Function 131 

siimake-hardcopy-stream, Function 116 

siivanilla-flavor, Flavor 129 

si:TanilIa-flaTor Methods 

:operation-handled-p 131 

:whicli-operatioDS 131 
signal, Function 102, 123, 126 
Signalling conditions 121 
Source Compare (m-x) 50 
Source Compare Merge (m-x) 50 

SPACE 6 

SPACE (Stepper command) 86 
Special commands (Debugger) 74 
Special Forms 

break 90 

multiple- value 107 

trace 86,89,91 

untrace 86, 87 

unwind-protect 127 
[Split Screen] 58,121 
Split Screen (m-x) 57 
standard-output. Variable 66 
Start Kbd Macro (c-x () 56 
[Step] 87,89 
step, Function 89 
:step. Option to trace 87, 89 
Stepper 86 
Stepper commands 

c-B 88 

c-E 88 

c-N 86 

c-u 88 

c-X 88 

SPACE 86 

Stepping 66, 86 

SUSPEND 68 

Swap Point And Mark (c-x c-x) 52 

Symbols 30 

sys:abort. Flavor 119 



TAB (Indent For Lisp) 21 
Tags Query Replace (m-x) 



51 



Tags Search (m-x) 51 
Tags tables 50 

termical-io, Variable 11, 101 
Text 

Killing 52 

Moving 5 1 

Yanking 52 
[Trace] 85.89 
Trace (m-x) 85, 89 
trace Options 

:arg 87 

:argpdl 87 

:botli 87 
127 :break 87,91 

:cond 87 

:entry 87 

:eBtrycond 87 

:entry print 87 

lerror 87, 91 

:exit 87 

;exitbreak 87, 91 

:exitcond 87 

texitprint 87 

:nil 87 

:print 87 

:step 87, 89 

:Talue 87 

iwherein 87 
trace. Special Form 86, 89, 91 
Tracing 84 

tv:any-tyi-mixin. Flavor 118 
tv:atty-tyi-mixiD Methods 

:auy-tyi 119 
tvicboose-variable-valuest Function 114, 121 
tT:choose-variabIe-yalues Options 

:f unction 121 
tTtgraphics-mixin, Flavor 106 
tv:graphics-mixin Methods 

:drair-!ine 11, 106 
tv:!ist-mouse-buttons-mixin, Flavor 118 
tTimake-blisker, Function 127 
tv:make-window. Function 102, 112, 115, 118 
tvcminimum-irindow. Flavor 107 
tv:minimuni-wittdow Init Options 

:blinker-p 1Q6' 

:edges-from 106 

:expose-p 106 

:minimum-height 106 

tminimum-width 106 
tTiminimum-windoir Methods 

:iBside-size 107 
tT:process-mixin, Flavor 118 
tviprocess-mixin Init Options 

:process 118 
tTUbeet, Flavor 127 
tv:sheet Methods 



Ptogram Development Tools and Techniques 173 

Symbolics, Inc. 



ichange-of-size-or-margins 109 

unit 109 

:refresli 109, 120 
tTisheet-folIowing-blinker, Function 127 
tv:window. Flavor 102, 105, 106, 107 
Two Windows (c-X 2) 57 
tjpep, Function 129 

unbreakon. Function 90 

[Untrace] 87 

untrace, Special Form 86, 87 
unwind-protect, Special Form 127 
Up Comment Line (m-p) 20 
Update Attribute List (m-x) 9 

:value. Option to trace 87 

values, Variable 89 

vanilla-flavor, Flavor (in package si:) 129 

Variables 32 

arglist 89 

query-io 126, 127 

Standard-output 66 

terminal-io 11,101 

values 89 
View Directory (m-x) 38 
View Two Windows (c-X 3) 57 

what-files-calL Function 32 

Where Is Symbol (m-x) 3 1 

where-is. Function 31 

[Wherein] 87 

: wherein. Option to trace 87 

twhich-operations. Method for si:vanilla-flavor 131 

who-calls. Function 32 

iwho-line-documentation-string Method 119 

Whoppers 108 

window. Flavor (in package tv:) 102, 105, 106, 107 

Windows 

Choose variable values 114, 119 

Multiple 57 
with-open-stream. Macro 116 

Yank (c-y) 54 
Yank Pop (m-v) 54 
Yanking text 52 
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The Lisp Machine software development environment contains many help facilities. This 
document summarizes the facilities for flnding out information about the program you are writing 
and about the general state of your Lisp environment. 

This is not a document about program development and not a document about help facilities in 
general. It is a collection of the support tools and facilities available for Hnding the kind of 
information that you need while programming. It is not exhaustive but suggestive. It does not 
recommend strategies for applying these facilities but rather lays out what is available for creating 
a personal style of using the Lisp Machine effectively. 

The document contains three parts. The first part explains some interaction conventions for name 
completion and using the mouse to find information. The second part contains a summary by 
topic of Zmacs and Lisp functions that provide information or assistance during programming. 
The third part is an alphabetical reference listing of the functions that appear in the summary list. 

This document is related to several other documents: 

Lisp Machine Summary 
Lisp Machine Manual 
Zmacs Manual 

Refer to these other documents for related information and explanations of terminology. 



Interaction Conventions 

The Lisp Machine software has some general interaction conventions. For example, many editor 
commands offer name completion. You can apply these facilities to exploring the command space 
of the machine. This section describes some general facilities and strategies for making more 
effective use of the machine. 

Mouse documentation line 

The mouse documentation line contains information about what different mouse clicks mean. As 
you move the mouse across different mouse-sensitive areas of the screen, the mouse documentation 
line changes to reflect the changing commands available. 

When no documentation appears, it does not necessarily mean that the mouse clicks are 
undefined. Not all programs have provided material for the mouse documentation line. When 
the mouse documentation line is blank at "top level" in a window, the mouse usually offers some 
standard commands. mouse-L selects a window; mouse-R brings up either the system menu or a 
menu specific to the application. 

Zmacs Completion 

Zmacs minibuffer commands offer completion over various name spaces. Completion is a facility 
for reducing the number of keys you need to type to specify a name. As-soon as you have typed 
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enough characters for a name to be recognized as unique, you can ask for completion. Up until 
then, you can ask to see which names are possible completions of what you have typed. You can 
tell when completion is available; the notation "(Completion)" appears at the right end of the 
minibuffer label line. 

Completion for extended commands (m-X commands) 

The following table summarizes the keys that control completion for entering extended commands. 

Key Action in m-X commands 

SPACE Completes the words up to the current word, as far as they are unique. 

HELP or C-? Shows the possible completions in the typeout area. 

mouse-R Pops up a menu of the possible completions. 

c-/ Runs Apropos for each of the partially typed words in the name. 

flLTMODE Displays the full command name, if possible. 

RETURN, END Confirms the command when possible, whether or not you have seen its full name. 

Request completion by typing either fiLTMODE or RETURN. Using flLTMODE shows the completed 
name, requiring a further RETURN to confirm it; using RETURN gets you completion and 
conflrmation in one step. 

Any time you are typing in a Zmacs extended command name, completion is available. Zmacs 
command name completion works on initial substrings of each word in the command. For 
example, "m-X e z" is enough to specify the extended command "Edit Zmacs Command". 

Until Zmacs can recognize the name as unique, your request for completion just completes as far 
as possible. Using flLTJIODE at this point moves the input cursor to the first ambiguous place in 
the command name. 

Whenever you are entering a name in a minibuffer that offers completion, you can find out all 
possible completions of what you have typed so far. Two styles are possible. Using HELP or c-? 
shows the list of completions in the typeout area; the names are mouse-sensitive. Using mouse-R 
shows the list in a pop-up menu. One good strategy for browsing is to look at the list of 
completions for initial substrings that are common command verbs, like "list" or "set". 

Completion for m- . 

The m-. (Edit Definition) command offers completion over the set of names that is in the files 
that have already been loaded into editor buffers. In this case, you request completion with 
flLTMODE and then confirm it with RETURN. 

m-. offers initial substring name completion, with hyphens rather than spaces delimiting the 
words. For example, "e-d-l" would be sufficient for specifying edit-definition-internal 
(assuming that Zmacs had previously parsed the source file containing it into a buffer). 

Completion In other contexts 

Completion is available in several other contexts, for example, buffer names and package names. 
We are gradually extending the contexts in which completion is available. Be on the lookout for 
the presence of "(Completion)" in the minibuffer label line. The conventions for extended 
commands usually apply. 



Symbolics. Inc. 2 November 1982 



Program Development Help Facilities 



Symbolics, Inc. 



Typeout windows in Zmacs 

Most of the Zmacs commands for looking up information display the information in a typeout 
window. A typeout window overlays the current buffer display with its contents and disappears as 
soon as you type any character. Most typeout windows contain mouse-sensitive items. In 
particular, Zmacs commands and Lisp function specs are mouse-sensitive and small menus of 
operations on the names are available (Arglist, Edit DeHnition, and so on). See the mouse 
documentation line. 

HELP l(ey in any Zmacs editing window 

The HELP Icey enables you to locate help material that is relevant to the current context. 
Individual programs are responsible for providing the routines that support the HELP key. The 
most complex general help facility is that provided by Zmacs editing windows. The HELP key 
provides access to a number of distinct kinds of help, depending on the key you press after the 
HELP key. 

Command Description 

HELP ? Displays a brief summary of the Zmacs help options (rather like the rest of this 

chart). 

HELP fi For looking up all Zmacs commands whose names contain a speciHed substring. 

You type the substring. Zmacs displays the one-line documentation for the 
command and which key invokes it in the current context, if any. See HELP V 
for looking up variable names. The "A" stands for "apropos". When people say, 
"Use Apropos," they are referring to this function. 

HELP C For looking up which command is bound to a particular key. You type the key; 

Zmacs displays the name of the command and its summary paragraph. HELP C 
uses Self Document. 

HELP D For looking up the summary paragraph for a Zmacs command. You enter the 

command name. Completion is available. It does not tell you how to invoke a 
command. Use HELP U for that. HELP D uses Describe Command. 

HELP L For finding out what you did that caused unexpected behavior. Zmacs displays a 

representation of the last 60 keys that you pressed. HELP L uses What Lossage. 

HELP U For undoing the last major operation. Zmacs preserves a copy of the buffer 

before doing certain operations, in particular, sorting and filling. You can revert 
to the state prior to one of those kinds of operations by using HELP U. Zmacs 
queries you whether to go ahead with undoing; the only information you have 
about what is being undone is the name of the class of operation, for example, 
"fill" or "sort". HELP U uses Undo. 

HELP y For looking up all Zmacs user variables whose print names contain a specified 

substring. You type the substring. Zmacs displays the variable names and their 
current values. See HELP R for looking up command names. HELP U uses 
Variable Apropos. 

HELP U For finding the key assignment for a particular command. You type the 

command name; Zmacs displays the current key assignment. Completion is 
available. HELP 14 uses Where Is. 
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Notation Conventions 

The keys with black lettering (like SHIFT or METfl) are shift keys, designed to be pressed in 
combination with other keys. They do not themselves transmit characters. Their combinations 
are shown hyphenated to remind you to press them at the same time as the associated key, not 
before. 

The keys with white lettering (like X or SYSTEM) all transmit a character. Combinations of these 
keys are meant to be pressed in sequence, for example, SYSTEM L means to press the SYSTEM key, 
release it, and then press the L key. 

The CTRL and METfi key combinations are abbreviated with c- and m-; the SUPER, HYPER, and 
SHIFT keys with s-, h-, and sh-, respectively. For example, the combined key press METFI-X is 
pronounced "meta x" and written as "m-X". 
This document uses the following notation conventions: 

Appearance in document Representing 

send, chaos:host-up Printed representation of Lisp objects in running text. 

RETURN, ABORT, c-F Keyboard keys. 

SPACE Space bar. 

login Literal type-in. 

(make -symbol "foo") Lisp code examples. 

function name argl arg2 Syntax descriptions of definitions. 

Undo, Tree Edit Any Command names in Zmacs and Zmail appear with initial letter of 

each word capitalized. 

Insert File (m-X) Extended command names in Zmacs and Zmail. Use m-X to invoke 

one. 

[Map Over] Menu items. 

(mouse-R) Mouse clicks; L=left, M=middle, R=right. 

Mouse commands use notations for menu items and mouse clicks in the following ways: 

Square brackets delimit a mouse command; slashes (/) separate the members of a compound 
mouse command. The notation indicates which button to click only when that differs from the 
standard. For a single menu item, always click left. For example, the following two commands 
are exactly the same: 

[Previous] 
[(mouse-L) Previous] 

For a compound command, always click right on each menu item except the last, where you click 
left. For example, the following two compound commands are exactly the same: 

[Map Over / Move / Hardcopy] 

[(mouse-R) Map Over / (mouse-R) Move / (mouse-L) Hardcopy] 

For all other cases, the notation shows explicitly which button to click. For example: 

[Map Over / (mouse-M) Move] 
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Some more examples: 

- Suppose you are to click right on menu item [Map Over], then click right on menu 
item [Move], then click left on menu item [Hardcopy]. The notation is: 

[Map Over / Move / Hardcopy] 

- Suppose you are to click left on menu item [Previous]. The notation is: 

[Previous] 

- Suppose you are to click right on menu item [Map Over], then click middle on menu 
item [Move]. The notation is: 

[Map Over / (mouse-M) Move] 

- Suppose you are to click right on menu item [Previous]. The notation is: 

[(mouse-R) Previous] 

In this document, all Zmacs commands appear by name rather than by key binding. Command 
tables indicate whether the command has a standard key binding or whether it must be used as 
an extended command. For example. Edit Zmacs Command is an extended command and 
requires that you invoke it with m-X. Forward Word is bound to the m-F key; you invoke it by 
pressing the key. 

Command Type of command 

Edit Zmacs Command (m-X) An extended command 

Forward Word (m-F) A command with a standard key binding 

Find File (c-X c-F) A command with a standard key binding 

Functions and their arguments appear in the following kind of summary line: 

(apropos strine pgckaee inferiors superiors) 

Words in italics are the arguments to the function. The words reflect the meaning of the 
argument. Underlined words are optional arguments; you can leave them out. The reference 
description for the function explains the meanings of the arguments and the default values for 
optional arguments. 
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Summary of Functions in Different Contexts 

Both Zmacs and Lisp offer facilities for finding information either about themselves or about the 
current environment. In addition, Zmacs offers ways to find information about Lisp functions 
and variables. 

This section lists the names of the functions and commands that are avaUable, grouped according 
to the context in which they are available. The purpose of this section is to summarize the 
capabilities and to help you determine both the overall contexts for which you can find help and 
a particular function that might be what you are looking for. Explanations for each of these 
functions appear in an alphabetical listing in the third part of this document. 

Zmacs commands for finding out about the state of buffers 

Edit Buffers (m-X) 

Edit Changed Definitions (m-X) 

Edit Changed Definitions Of Buffer (m-X) 

List Buffers (c-X c-B) 

List Changed Definitions (m-X) 

List Changed Definitions Of Buffer (m-X) 

List Definitions (m-X) 

List Matching Lines (m-X) 

Print Modifications (m-X) 

Select System as Tag Table (m-X) 

Tags Search (m-X) 

Zmacs commands for finding out about the state of Zmacs 

Apropos (HELP fl, m-X) 

Describe Variable (m-X) 

Edit Zmacs Command (m-X) 

List Commands (m-X) 

List Registers (m-X) 

List Some Word Abbrevs (m-X) 

List Tag Tables (m-X) 

List Variables (m-X) 

List Word Abbrevs (m-X) 



Zmacs commands for finding out about Lisp 

Brief Documentation (c-sh-D) 

Describe Variable At Point (c-sh-V) 

Edit Callers (m-X) 

Edit Definition (m-. ) 

Edit File Warnings (m-X) 

Function Apropos (m-X) 

List Callers (m-X) 

List Matching Symbols (m-X) 

Long Documentation (m-sh-D) 
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Multiple Edit Callers (m-X) 
Multiple List Callers (m-X) 
Quick Arglist (c-sh-fl) 
Where Is Symbol (m-X) 



Zmacs commands for finding out about flavors 

Describe Flavor (m-X) 

Edit Combined Methods (m-X) 

Edit Methods (m-X) 

List Combined Methods (m-X) 

List Methods (m-X) 



Zmacs commands for interacting with Lisp 

Break (BRERK) 

Compile And Exit (m-2) 

Compile Buffer (m-X) 

Compile Changed Definitions (m-X) 

Compile Changed Definitions Of Buffer (m-sh-C, m-X) 

Compile File (m-X) 

Compile Region (c-sh-C, m-X) 

Compiler Warnings (m-X) 

Edit Compiler Warnings (m-X) 

Evaluate And Exit (c-m-2) 

Evaluate And Replace Into Buffer (m-X) 

Evaluate Buffer (m-X) 

Evaluate Changed Definitions (m-X) 

Evaluate Changed Definitions Of Buffer (m-sh-E, m-X) 

Evaluate Into Buffer (m-^-x) 

Evaluate Minibuffer (m-flLTMODE) 

Evaluate Region (c-sh-E, m-X) 

Evaluate Region Hack (m-X) 

Evaluate Region Verbose (c-m-sh-E) 

Load Compiler Warnings (m-X) 

Macro Expand Expression (c-sh-M, m-X) 

Trace (m-X) 

Quit (c-E) 



Lisp facilities for finding out about Lisp 

(apropos string packaee inferiors superiors'^ 
(arglist function flag) 
(describe object) 
(describe-area area-name) 
(describe-def struct instance structure-name) 
(describe-flavor flavor-name) 
(describe-pacicage package-name) 
(describe-system system-name) 
(disassemble function) 
(documentation function) 
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(si:flavor-allowed-init-keywords flavor-name) 

(inspect object) 

(compiler:Ioad-compiler-warnings file flush- flaei 

(mexp) 

(trace specs) 

(untrace stfecs) 

(variable-boundp variable) 

(what-files-call string vackaee) 

(where-is symbol package) 

(who-calls symbol package inferiors superiors) 
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Reference Description of Functions 

This section contains a summary paragraph of documentation for each of the information-finding 
commands and functions appearing in the summary lists of this document. 

This reference list is in alphabetical order by name of the command or function. Zmacs editor 
commands appear according to the names of the commands that implement them, rather than 
according to the names of the keys that invoke them. For example, m-X Compile Buffer appears 
under "C" rather than under "M"; c-sh-fl appears under "Q" (ijecause its name is Quick Arglist) 
rather than under "C". For commands that are usually invoked by a single key rather than by 
m-X, the key name appears with the command. (Remember you can always use HELP U to find a 
key name.) 

Some Zmacs commands come in pairs, for example. List Callers and Edit Callers. The commands 
are very similar. The List version allows you to just look at the list or to decide to start editing 
the items in the list. The list items are always mouse-sensitive. For the Edit version of the 
command, c-. is always the command for moving to the next item. 

Apropos (HELP fi, m-X) 

Displays all the Zmacs commands whose names contain a specified substring. 
You type the substring. Zmacs displays one line of documentation for the 
command and which key invokes it in the current context, if any. 

(apropos string packaee inferiors superiors) 

Displays all of the symbols whose print names contain the string. By default, it 
looks in the global package and its descendants, but you can specify a package 
name. For symbols that have function bindings, it displays the argument list. 
For symbols that are bound, it displays a notation "Bound", apropos returns 
the list of symbols that it found. 

(apropos "forward" 'zwei) 

(apropos "process" 'global n11) 

The second example looks only in the global package, not in any of its 
inferiors. 

(arglist function flag) (see also Quick Arglist) 

Returns a representation of the arguments that the function expects. When the 
original function definition contained an arglist declaration, arglist returns 
that list when flag is not specified or nil. When flag is not nil, then arglist 
returns the real argument list from the function. When the original function 
used a values declaration, arglist returns the names for the values returned by 
the function. 

(arglist 'make-array) 

You cannot use arglist to find the arguments for combined methods. 

BRERK Enters a Lisp Listener from the current window. It uses the screen area of the 

frame that was selected when you used BRERK. When you use it from the 
editor, any Lisp forms you type are evaluated in the current package (the one 
showing in the status line). Use RESUME to return to the original context. 

Brief Documentation (c-sh-D) (see also Long Documentation) 

Displays brief documentation for the specified Lisp function. By default, it 
displays documentation for the current function. With a numeric argument, it 
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prompts for a function name, which you can either type in or select with the 
mouse. It displays the first line from the summary paragraph in the echo area. 

c-m-sh-E See Evaluate Region Verbose. 

c-sh-fl See Quick Arglist. 

c-sh-C See Compile Region. 

c-sh-D See Brief Documentation. 

c-sh-E See Evaluate Region. 

c-sh-y See Describe Variable At Point. 

Compile And Exit (ni-2) 

Compiles the buffer and returns from top level. It selects the window from 
which the last (ed) function or the last debugger c-E command was executed. 

Compile Buffer (m-X) 

Compiles the entire buffer. With a numeric argument, it compiles from point 
to the end of the buffer. (This is useful for resuming compilation after a prior 
Compile Buffer has failed.) 

Compile Changed Definitions (m-X) 

Compiles any definitions that have changed in any Lisp mode buffers. With a 
numeric argument, it queries individually about whether to compile each 
changed deflnition. 

Compile Changed Definitions Of Buffer (m-sh-C, m-X) 

Compiles any definitions in the current buffer that have been changed. With a 
numeric argument, it prompts individually about whether to compile each 
changed definition. 

Compile File (m-X) 

Compiles a file, offering to save it first. It prompts for a file name in the 
minibuffer, using the file associated with the current buffer as the default. It 
offers to save the file if the buffer has been modified. 

Compile Region (c-sh-C, m-X) 

Compiles the region, or if no region is defined, the current definition. 

Compiler Warnings (m-X) (see also Edit Compiler Warnings) 

Puts all pending compiler warnings in a buffer and selects that buffer. It loads 
the compiler warnings database into a buffer called *Compiler-Warnings-l*, 
creating that buffer if it does not exist. 

(describe object) (see also inspect) 

Displays available information about an object, in a format that depends on the 
type of the object. For example, describing a symbol displays its value, 
definition, and properties, describe returns the object, 
(describe *t1ine:get-tiine) 

(describe-area area-name) 

Displays attributes of the specified area. 

(descr1be-area (Xarea-nunber 'foo)) 
(describe-area 'working-storage-area) 

(describe-defstruct instance structure-name) 

Displays a description of the instance, showing the contents of each of its slots. 
structure-name is not necessary for named structures but must be provided for 
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unnamed structures. When you use supply structure-name, you force the 
function to use that structure name instead of letting the system figure it out; 
in addition, it overrides the :describe option for structures that know how to 
describe themselves. 

Describe Flavor (m-X) (see also describe-flavor) 

Displays a description of a flavor. It reads a flavor name via the mouse or 
from the minibuffer using completion. It displays a description of the flavor in 
a typeout window. The description includes names of flavors that the specified 
one directly depends on and names of flavors that depend on it. It also 
displays the documentation and the names of its instance variables. 

(describe-flavor flavor-name) (see also Describe Flavor) 

Displays descriptive information about a flavor, 
(describe-flavor 'tv:bas1c-inenu) 

(describe-package package-name) 

Displays information about a package, 
(describe-package 'zwe1) 

That example is the same as this one: 

(describe (pkg-flnd-package 'zwel)) 

(describe-system system-name) 

Displays information about a system, including the name of the file containing 
the system declaration and when the files in the current version of the system 
were compiled. 

Describe Variable (m-X) 

Displays the documentation and current value for a Zmacs variable. It reads 
the variable name from the minibuffer, using completion. 

Describe Variable At Point (c-sh-V) 

Displays information, in the echo area, about the current Lisp variable. The 
information includes whether the variable is declared special, whether it has a 
value, what file defines it, and whether it has documentation put on by defvar 
or defconst. When nothing is available, it checks for lookalike symbols in 
other packages. 

(disassemble function) (see also mexp) 

Displays the macro-instructions for the function. It does not work for 
functions that are not compiled or that are implemented in microcode, like 
cons or car. (See How to Read Assembly Language in the Lisp Machine 
Manual.) 

(disassemble 'plus) 

Use this function for things like finding clues about whether a macro is being 
expanded correctly. 

(documentation function) 

Returns the documentation string for a function or variable. It returns nil 
when no documentation has been provided. (Note: as of Release 4.0, very few 
functions have associated documentation.) 

(documentation 'zwel :com-quick-arg1ist) 

Edit Buffers (m-X) (see also List Buffers) 

Displays a list of all buffers, allowing you to save or delete buffers and to 
select a new buffer. A set of single character subcommands lets you specify 
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various operations for the buffers. For example, you can mark buffers to be 
deleted, saved, or not modified. Use HELP to see further explanation. The 
buffer is read-only; you can move around in it by searching and with 
commands like c-N or c-P. 

Edit Callers (m-X) (see also List Callers, Multiple Edit Callers) 

Prepares for editing all functions that call the speciHed one. It reads a function 
name via the mouse or from the minibuffer with completion. By default, it 
searches the current package. You can control the package being searched by 
giving the function an argument. With c-U, it searches all packages; with c-U 
c-U, it prompts for a package name. It selects the first caller; use c-. (Next 
Possibility) to move to a subsequent definition. It takes about 5 minutes to 
search all packages. 

Edit Changed Definitions (m-X) (see also List Changed Definitions) 

Determines which definitions in any Lisp mode buffer have changed and selects 
the Hrst one. It makes an internal list of all the deHnitions that have changed 
in the current session and selects the first one on the list. Use c-. (Next 
Possibility) to move to a subsequent definition. Use a numeric argument to 
control the starting point for determining what has changed: 

1 For each buffer, since the file was last read (the default). 

2 For each buffer, since it was last saved. 

3 For each definition in each buffer, since the definition was last compiled. 

Edit Changed Definitions Of Buffer (m-X) (see also List Changed DeHnitions Of Buffer) 

Determines which definitions in the buffer have changed and selects the first 
one. It makes an internal list of all the definitions that have changed since the 
buffer was read in and selects the first one on the list. Use c-. (Next 
Possibility) to move to subsequent definitions. Use a numeric argument to 
control the starting point for determining what has changed: 

1 Since the file was last read (the default). 

2 Since the buffer was last saved. 

3 Since the definition was last compiled, for each definition in the buffer. 

Edit Combined Methods (m-X) (see ako List Combined Methods) 

Prepares to edit the methods for a specified message to a specified flavor. It 
prompts first for a message name, then for a flavor name. It selects the first 
combined method component. Use c-. (Next Possibility) to move to a 
subsequent definition. The definitions appear in the order that they would be 
called when the message was sent. Error messages appear when the flavor does 
not handle the message and when the flavor requested is not a composed, 
instantiated flavor. 

Edit Compiler Warnings (m-X) (see also Compiler Warnings) 

Prepares to edit all functions whose compilation caused a warning message. It 
queries, for each of the files mentioned in the database, whether you want to 
edit the warnings for the functions in that file. It splits the screen, putting the 
warning message in the top window. The bottom window displays the source 
code whose compilation caused the message. Use c-. (Next Possibility) to 
move to a subsequent warning and source function. After the last warning, it 
returns the screen to its previous configuration. 

Edit Definition (m-.) 

Prepares to edit the definition of a function, variable, flavor, or anything else 
defined with a "defsomething" special form. It prompts for a definition name 
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from the minibuffer. Name completion is available for definitions in Hies that 
have already been loaded into buffers. You can select a name by clicking the 
mouse over a deHnition name in the current buffer. It selects the buffer 
containing the deflnition for that name, first reading in the file if necessary. 
With a numeric argument, it selects the next deHnition that satisHes the most 
recent name given. It tells you in the echo area when it finds more than one 
definition for a name. 

Edit File Warnings (m-X) 

Prepares to edit any functions in a speciHed file for which warnings exist. It 
prompts for a file name, which can be either a source file or a compiled file. It 
splits the screen, putting a warning message from the warnings database in the 
top window. The bottom window displays the source code whose compilation 
caused the message. If the database does not contain any warnings for this file, 
it prompts for the name of a file containing the warnings. Use c-. (Next 
Possibility) to move to a subsequent warning and source function. After the 
last warning, it returns the screen to its previous configuration. 

Edit Methods (m-X) (see also List Methods) 

Prepares to edit all the methods on any flavor for a particular message. It 
prompts for a message name. It finds all the flavors with handlers for the 
message, makes an internal list of the method names, and selects the definition 
for the first one. Use c-. (Next Possibility) to move to subsequent definitions. 

Edit Zmacs Command (m-X) 

Finds the source for the function installed on a key. You can press any key 
combination or enter an extended command name. Use a numeric argument to 
edit the function that implements a prefix command (like m-X or c-X). 

Evaluate And Exit (c-m-2) 

Evaluates the buffer and returns from top level. It selects the window from 
which the last (ed) function or the last debugger c-E command was executed. 

Evaluate And Replace Into Buffer (m-X) 

Evaluates the Lisp object following point in the buffer and replaces it with its 
result. 

Evaluate Buffer (m-X) 

Evaluates the entire buffer. With a numeric argument, it evaluates from point 
to the end of the buffer. 

Evaluate Changed Definitions (m-X) 

Evaluates any definitions that have changed in any buffers. With a numeric 
argument, it prompts individually about whether to evaluate particular changed 
definitions. 

Evaluate Changed Definitions Of Buffer (m-sh-E, m-X) 

Evaluates any definitions in the current buffer that have been changed. With a 
numeric argument, it prompts individually about whether to evaluate particular 
changed definitions. 

Evaluate Into Buffer (m-X) 

Evaluates a form read from the minibuffer and inserts the result into the 
buffer. You enter a Lisp form in the minibuffer, which is evaluated when you 
press END. The result of evaluating the form appears in the buffer before 
point. With a numeric argument, it also inserts any typeout that occurs during 
the evaluation into the buffer. 
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Evaluate Minibuffer (m-flLTtlODE) 

Evaluates forms from the minibuffer. You enter Lisp forms in the minibuffer, 
which are evaluated when you press END. The value of the form itself appears 
in the echo area. If the form displays any output, that appears as a typeout 
window. 

Evaluate Region (c-sh-E, m-X) 

Evaluates the region. When no region has been defined, it evaluates the 
current definition. It sYiovrs the results in the echo area. 

Evaluate Region Hack (m-X) 

Evaluates the region, ensuring that any variables appearing in a def var have 
their values set. When no region has been defined, it evaluates the current 
definition. It shows the results in the echo area. 

Evaluate Region Verbose (c-m-sh-E) 

Evaluates the region. When no region has been defined, it evaluates the 
current deHnition. It shows the results in a typeout window. 

(flavor-allowed-init-keywords flavor-name) (In sip 

Returns a list containing the init keywords and inittable instance variables 
allowed for a particular flavor. 

(si :flavor-a11owed-in1t-keyv«)rds *tv:bas1c-menu) 

Function Apropos (m-X) 

Displays all the Lisp functions whose print names contain a particular substring. 
It reads the substring from the minibuffer. By default, it searches the current 
package. You can control the package being searched by giving the function an 
argument. With c-U, it searches all packages; with c-U c-U, it prompts for a 
package name. 

(inspect object) (see also describe) 

Creates or selects an Inspector window and displays available information about 
an object, inspect and describe provide similar information, except that 
inspect is an interactive facility for further exploring a data structure. 

(Inspect tv:selected-w1ndow) 

(Inspect (tv:w1ndow-under-mouss)) 

List Buffers (c-X c-B) (see also Edit Buffers) 

Prints a list of all the buffers and their associated files. The lines in the list 
are mouse-sensitive, offering a menu of operations on the buffers. Clicking left 
on a line selects the buffer. For buffers with associated files, the version 
number of the file appears. For buffers without associated files, the size of the 
buffer in lines appears. For Dired buffers, the pathname used for creating the 
buffer appears as the version. The list of buffers appears sorted in order of last 
access, with the currently selected one at the top. You can inhibit sorting by 
setting zwei:*sort-zniacs-buffer-list''' to nil. 

List Callers (m-X) (see also Edit Callers, Multiple List Callers) 

Lists all functions that call the specified function. It reads a function name via 
the mouse or from the minibuffer with completion. By default, it searches the 
current package. You can control the package being searched by giving the 
function an argument. With c-U, it searches all packages; with c-U c-U, it 
prompts for a package name. The names are mouse-sensitive. Use c-. (Next 
Possibility) to start editing the definitions in the list. It takes about 5 minutes 
to search all packages. 
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List Changed Definitions (m-X) (see also Edit Changed Definitions) 

Displays a list of any definitions that have been edited in any buffer. Use c-. 
(Next Possibility) to start editing the definitions in the list. Use a numeric 
argument to control the starting point for determining what has changed: 

1 For each buffer, since the file was last read (the default). 

2 For each buffer, since it was last saved. 

3 For each definition in each buffer, since the definition was last compiled. 

List Changed Definitions Of Buffer (tn-X) (see also Edit Changed Definitions Of Buffer) 

Displays the names of definitions in the buffer that have changed. It makes an 
internal list of the definitions changed since the buffer was read in and offers 
to let you edit them. Use c-. (Next Possibility) to move to subsequent 
definitions. Use a numeric argument to control the starting point for 
determining what has changed: 

1 Since the file was last read (the default). 

2 Since the buffer was last saved. 

3 Since the definition was last compiled, for each definition in the buffer. 

List Combined Methods (m-X) (see also Edit Combined Methods) 

Lists the methods for a specified message to a specified flavor. It prompts first 
for a message name, then for a flavor name. It lists the names in a typeout 
window. Error messages appear when the flavor does not handle the message 
and when the flavor requested is not a composed, instantiated flavor. Use c-. 
(Next Possibility) to start editing the definitions in the list. 

List Commands (m-X) 

Lists names and one-line summaries for all extended commands available in the 
current context. It displays the names in a typeout window. The list is not 
sorted. 

List Definitions (m-X) 

Displays the definitions from a specified buffer. It reads the buffer name from 
the minibuffer, using the current buffer as the default. It displays the list as a 
typeout window. The individual definition names are mouse-sensitive. 

List Matching Lines (m-X) 

Displays all the lines following point in the current buffer that contain a given 
string. It prompts for the string in the minibuffer. With a numeric argument, 
it shows only the first n occurrences of the string following point. It does not 
accept a numeric argument. The lines are mouse-sensitive. 

List Matching Symbols (m-X) 

Lists the symbols that satisfy a predicate. It prompts for a predicate lambda 
expression of one argument. The predicate gets compiled, for speed. The 
predicate must return something other than nil for the symbol to be included 
in the list. For example 

you pressed: m-X L M S 
minibuffer contains: '(LAMBDA (SYMBOL)) 
revised minibuffer: '(LAMBDA (SYMBOL) (string-search "foo" symbol)) 
By default, it searches the current package. You can control the package being 
searched by giving the function an argument. With c-U, it searches all 
packages; with c-U c-U, it prompts for a package name. It selects the first one; 
use C-. (Next Possibility) to move to a subsequent definition. 

List Methods (m-X) (see also Edit Methods) 
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Lists all the function specs for all methods on any flavor that handle a 
particular message. It prompts for the message name. It finds all the flavors 
with methods for the message and displays the information in a typeout 
window. The function specs are mouse-sensitive. 

List Registers (m-X) 

Displays names and contents of all defined registers. Use Apropos to see 
commands for manipulating registers. 

List Some Word Abbrevs (tn-X) 

Lists the abbreviations or expansions that contain the given string. Use 
Apropos to see the other abbreviation commands. 

List Tag Tables (m-X) 

Lists the names of all the tag tables currently available. Use Apropos to see 
other commands using tags. 

List Variables (m-X) 

Lists all Zmacs variable names and their values. With a numeric argument, it 
also displays the documentation line for the variable. Zmacs variables are those 
that have been provided for customizing the editor. Their names differ from 
their internal Lisp names: 

Zmacs variable name: Fill Column 
Internal Lisp name: zwei:*fill-column* 

List Word Abbrevs (m-X) 

Lists all current abbreviations and their expansions. 

(load-compiler-warnings file flush- flag) (In compiler:) 

Loads a file containing compiler warning messages into the warnings database. 
The file should contain the printed representation of compiler warnings (as 
saved by print-compiler-warnings). It uses flush- flag to determine whether 
to replace any of the warnings already in the database. When the flag is not 
nil, it deletes any warnings associated with a source file before loading any new 
warnings for that file. Otherwise, it merges warnings from the file with those 
already in the warnings database. The default is t. 

Load Compiler Warnings (m-X) 

Loads a file containing compiler warning messages into the warnings database. 
It prompts for the name of a file that contains the printed representation of 
compiler warnings. It always replaces any warnings already in the database. 

Long Documentation (m-sh-D) (see also Brief Documentation) 

Displays the summary documentation for the specified Lisp function. It 
prompts for a function name, which you can either type in or select with the 
mouse. The default is the current function. 

in-. See Edit Definition. 

m-flLTMODE See Evaluate MiniBuffer. 

m-sh-C See Compile Changed Definitions Of Buffer. 

m-sh-D See Long Documentation. 

m-sh-E See Evaluate Changed Definitions Of Buffer. 

Macro Expand Expression (c-sh-M, m-X) 

Displays the macro expansion of the next Lisp expression in the buffer. It 
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reads the Lisp expression following point and expands all macros within it at all 
levels, displaying the result on the typeout window. With a numeric argument, 
it pretty-prints the result back into the buffer, immediately following the 
expression. 

(mexp) (see also disassemble) 

Displays the expansion of a macro. It prompts for a macro invocation to 
expand and then displays its expansion without evaluating it. It continues 
prompting until you enter something that is not a cons (for example, () stops 
it.) 

Multiple Edit Callers (m-X) (see also Edit Callers) 

Prepares for editing all functions that call the specified ones. It reads a 
function name from the minibuffer, with completion. It then keeps asking for 
another function name until you end it with just RETURN. By default, it 
searches the current package. You can control the package being searched by 
giving the function an argument. With c-U, it searches all packages; with c-U 
c-U, it prompts for a package name. It selects the first caller; use c-. (Next 
Possibility) to move to a subsequent definition. 

Multiple List Callers (m-X) (see also List Callers) 

Lists all the functions that call the specified functions. It reads a function 
name from the minibuffer, with completion. It continues prompting for a 
function name until you end it with just RETURN. By default, it searches the 
current package. You can control the package being searched by giving the 
function an argument. With c-U, it searches all packages; with c-U c-U, it 
prompts for a package name. Use c-. (Next Possibility) to start editing the 
definitions in the list. 

Print Modifications (m-X) 

Displays the lines in the current buffer that have changed since the file was 
first read into a buffer. With a numeric argument, it displays the lines that 
have changed since the last save. To provide context, it shows the first line of 
each section that contains a change, whether or not that line has changed. The 
lines are mouse-sensitive, allowing you to move to the location of a change. 

Quick Arglist (c-sh-fl) (see also arglist) 

Displays the argument list for the current function. With a numeric argument, 
it reads the function name via the mouse or from the minibuffer. When the 
original function uses a values declaration. Quick Arglist returns the names for 
the values returned by the function. 

Quit (c-2) Returns from top level. It selects the window from which the last (ed) 

function or the last debugger c-E command was executed. 

Select System as Tag Table (m-X) 

Creates a tags table for all the files in a system. It uses the file names as they 
appear in the defsystem function for that system. 

Tags Search (m-X) Searches all files in a tags table for a specified string. It reads the string from 
the minibuffer and then prompts for a tags table name. 

Trace (m-X) (see also untrace) 

Toggles tracing for a function. It uses the same interface for specifying options 
as the Trace program in the system menu. See Lisp Machine Manual, p. 457. 

(trace svecs\ (see also untrace) 
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Turns on tracing for a function. With no arguments, it returns a list of all 
things currently being traced. With no additional options, tracing displays the 
name and arguments for a function each time it is called and its name and 
value(s) each time it returns. Complex options are available for entering 
breakpoints or executing code conditionally during tracing. See Lisp Machine 
Manual, p. 457, and the Trace command in Zmacs. 

(trace foo bar) 

(trace #'(:iiiethod command-found :push)) 

Tracing very common functions (like format) or functions used by trace itself 
or by the scheduler (like time:get-time) can crash the machine. 

(untrace svecsS Turns off tracing for a function that is being traced. With no argument, it 
turns off tracing for all functions currently being traced. 

(variable-bonndp variable^ 

Returns nil or t indicating whether or not the variable is bound, 
(varlable-boundp tv:current-w1ndow) 

(what-files-call symbol packai^e) 

Displays the names of files that contain uses of symbol as a function, variable, 
or constant. It searches all the function cells of all the symbols in package. By 
default, it searches the global package and its descendants. It returns a list of 
the pathnames of the files containing the callers. 

Where Is Symbol (m-X) 

Displays the names of packages that contain symbols with the specified name. 

(where-is string pgckgge) 

Displays the names of all packages that contain a symbol whose print name is 
string. It ignores the case of string. By default, it looks in the global package 
and its descendants, where-is returns a list of the symbols that it finds, 
(where-is "foobar") 

(who-calls symbol package inferiors superiors) 

Displays a line of information about uses of the symbol as a function, variable, 
or constant. It searches all the function cells of all the symbols in package By 
default, it searches the global package and its descendants. It returns a list of 
the names of the callers. 

(who-calls 't1me:get-t1me 'hacks) 
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Notes 
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